@zalom/plastic 2.0.0-alpha.18 → 2.0.0-alpha.19

package/scripts/lib/action_graph_shim.rb

@@ -0,0 +1,277 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "graph_file"
+require_relative "graph_edges"
+require_relative "node_file"
+require_relative "savepoint"
+require_relative "work_graph_validator"
+
+# ActionGraphShim (intent 342, G9): a read-time backward shim that presents
+# any intent directory's actions/*.md as a node graph, in the record shape
+# NodeFile.parse returns, so 336, 338 and 339 read a legacy intent through
+# the same call they already use for an authored graph.md (spec.md D1-D18).
+#
+# Writes nothing, anywhere, ever (D1). An authored graph.md always wins over
+# the synthetic chain (D3) - the reverse of 334's forward shim, which
+# resolves content and prefers the older, richer source. This one resolves
+# structure, where an authored graph is the only real graph.
+module ActionGraphShim
+  module_function
+
+  # D10's heading test: unchanged, four tokens, verified correct on the live
+  # store. Governs only whether a "## Files ..." heading itself is negated
+  # (e.g. "## Files you must NOT change"), never the section body.
+  FILES_NEGATION_RE = /\bnot\b|\bnever\b|\bavoid\b|don't/i.freeze
+
+  # D19's body-truncation vocabulary: the four heading tokens plus the
+  # exclusion phrases the live corpus actually uses ("Out of bounds, owned
+  # by leads running in parallel right now:" matched none of the original
+  # four). Governs whether a body LINE truncates the files harvest -
+  # never the heading test above, which stays on FILES_NEGATION_RE.
+  FILES_EXCLUSION_RE = /\bnot\b|\bnever\b|\bavoid\b|don't|\bout of bounds\b|\bout of scope\b|\bhands off\b|\bleave alone\b|\bexcluded\b/i.freeze
+
+  BACKTICK_RE = /`([^`]+)`/.freeze
+  PROVEN_BY_LABEL_RE = /\AS\d+\z/.freeze
+
+  # :authored when graph.md exists, :actions when it does not but the intent
+  # holds at least one real action file (D7's exact realness test, reused
+  # rather than reimplemented so the shim can never disagree with
+  # Savepoint.has_real_action? about whether an intent has work in it), :none
+  # otherwise. A directory that does not exist returns :none and never
+  # raises.
+  def shape(intent_dir)
+    return :none unless intent_dir && File.directory?(intent_dir.to_s)
+    return :authored if File.exist?(File.join(intent_dir, "graph.md"))
+    return :actions if Savepoint.has_real_files_in?("actions", intent_dir)
+
+    :none
+  end
+
+  # The seven-key hash GraphFile.parse returns (ok:, goal:, decisions:,
+  # graph:, status:, verify:, errors:), for whichever shape the directory
+  # is in. On :authored this is literally GraphFile.parse, unmodified (D3).
+  # On :actions the same hash is built from the action files, with goal:,
+  # decisions: and status: nil (a 2024 action file was never asked for
+  # them) and verify: a fixed reason so a trivial-bar check the caller may
+  # run stays self-consistent. On :none it is GraphFile.parse's own
+  # not-found failure, produced by delegating to it rather than
+  # reformatting the message ourselves.
+  def view(intent_dir)
+    case shape(intent_dir)
+    when :authored
+      GraphFile.parse(File.join(intent_dir, "graph.md"))
+    when :actions
+      synth = synthetic_graph(intent_dir)
+      {
+        ok: synth[:errors].empty?,
+        goal: nil,
+        decisions: nil,
+        graph: synth,
+        status: nil,
+        verify: { reason: "backward shim: legacy actions/ carry no verify node" },
+        errors: synth[:errors],
+      }
+    else
+      # 342 post-execution review, should-fix 5: a nil intent_dir must never
+      # raise. shape(nil) is already nil-guarded, so `view` and `needs`
+      # honor the same contract rather than raising a File.join TypeError.
+      return GraphFile.failure(["graph file not found: #{intent_dir.inspect}"]) unless intent_dir
+
+      GraphFile.parse(File.join(intent_dir, "graph.md"))
+    end
+  end
+
+  # Node records for either shape (D8), always carrying NodeFile.parse's own
+  # key set (ok:, node:, kind:, files:, budget:, body:, errors:) plus
+  # needs:, path: and proven_by:. [] on :none, never a raise on a real
+  # directory.
+  def nodes(intent_dir)
+    case shape(intent_dir)
+    when :authored
+      authored_nodes(intent_dir)
+    when :actions
+      synthetic_nodes(intent_dir)
+    else
+      []
+    end
+  end
+
+  # The needs targets for one node id, under either shape; [] for an id the
+  # graph does not declare, and [] for a directory with no graph at all.
+  def needs(intent_dir, node_id)
+    graph = view(intent_dir)[:graph]
+    return [] unless graph
+
+    (graph[:edges] || {})[node_id] || []
+  end
+
+  # --- authored shape -------------------------------------------------------
+
+  def authored_nodes(intent_dir)
+    parsed = GraphFile.parse(File.join(intent_dir, "graph.md"))
+    edges = parsed.dig(:graph, :edges) || {}
+
+    # 342 post-execution review, nit 8: sort_key numerically over the
+    # basename, the same key the synthetic chain uses, so an authored
+    # intent with ten or more nodes orders n10 after n9 rather than
+    # lexically between n1 and n2.
+    Dir.glob(File.join(intent_dir, "nodes", "*.md"))
+       .sort_by { |path| sort_key(File.basename(path)) }
+       .map do |path|
+      nf = NodeFile.parse(path)
+      nf.merge(
+        needs: edges[nf[:node]] || [],
+        path: path,
+        proven_by: proven_by_labels(nf[:body].to_s)
+      )
+    end
+  end
+
+  # --- actions shape ----------------------------------------------------------
+
+  # {nodes:, edges:, errors:} built directly over the minted chain, in the
+  # same shape GraphEdges.parse returns, rather than rendering a "## Graph"
+  # section and reparsing it.
+  def synthetic_graph(intent_dir)
+    ids = real_action_files(intent_dir).each_index.map { |i| "n#{i + 1}" }
+    edges = {}
+    ids.each_with_index { |id, i| edges[id] = i.zero? ? [] : [ids[i - 1]] }
+    { nodes: ids, edges: edges, errors: [] }
+  end
+
+  def synthetic_nodes(intent_dir)
+    files = real_action_files(intent_dir)
+    files.each_with_index.map do |path, i|
+      id = "n#{i + 1}"
+      needs_targets = i.zero? ? [] : ["n#{i}"]
+      begin
+        text = File.read(path)
+        {
+          ok: true,
+          node: id,
+          kind: "work",
+          files: files_section_paths(text),
+          budget: nil,
+          body: text,
+          errors: [],
+          needs: needs_targets,
+          path: path,
+          proven_by: proven_by_labels(text),
+        }
+      rescue StandardError => e
+        {
+          ok: false,
+          node: id,
+          kind: "work",
+          files: [],
+          budget: nil,
+          body: nil,
+          errors: ["could not read #{path}: #{e.message}"],
+          needs: needs_targets,
+          path: path,
+          proven_by: [],
+        }
+      end
+    end
+  end
+
+  # Real action files (File.file?, non-zero size, Savepoint.stage_file_present?
+  # - D7's own three-part predicate, applied per file since has_real_files_in?
+  # only answers true/false), ordered by the integer trailing the basename,
+  # falling back to the basename itself so the key is a total order over
+  # every basename shape the live store holds (D4).
+  def real_action_files(intent_dir)
+    Dir.glob(File.join(intent_dir.to_s, "actions", "*.md"))
+       .select { |f| File.file?(f) && File.size(f) > 0 && Savepoint.stage_file_present?(f) }
+       .sort_by { |f| sort_key(File.basename(f)) }
+  end
+
+  def sort_key(basename)
+    m = basename.match(/\d+/)
+    m ? [0, m[0].to_i, basename] : [1, 0, basename]
+  end
+
+  # The first heading whose leading token is "Files" (case-insensitively),
+  # unless the heading text carries a negation, in which case it is not a
+  # files section and the search continues (D10). Paths come out of that
+  # section's BODY through extract_files_paths, which is itself
+  # negation-aware and fence-aware (D17, D18). No qualifying heading gives
+  # [] (D9).
+  def files_section_paths(text)
+    NodeFile.split_by_headings(text).each do |heading, section|
+      next unless files_heading?(heading)
+
+      return extract_files_paths(section.to_s)
+    end
+    []
+  end
+
+  # Fence-aware (D18) and negation-aware over the section body, not only
+  # its heading (D17). D10 already stops a heading like "## Files you must
+  # NOT change" from being read as a files section at all; this handles
+  # the equally common case where a legitimate "## Files to touch" heading
+  # is followed, inside the same section, by an out-of-bounds paragraph -
+  # live on this intent's own dogfood fixture. A fenced block is dropped
+  # before anything else runs, reusing NodeFile.each_fence_line rather than
+  # a bare backtick scan, which is exactly what that helper exists to
+  # prevent.
+  #
+  # Lines are scanned in document order; harvesting stops at the first line
+  # an exclusion GOVERNS (D19), not merely mentions - a negation is a false
+  # positive as often as a real exclusion clause, since an action file
+  # routinely annotates an in-bounds path with a "do NOT rename it" aside.
+  # governs_exclusion? draws the line: the match governs when it begins
+  # before the line's first backtick (an exclusion clause introducing
+  # paths) or when the line carries no backtick at all (a bare warning
+  # sentence); it annotates, and the line is kept, when the match falls
+  # after the first backtick (a parenthetical about a path already named).
+  # Any span that still holds a newline is rejected as a backstop: a path
+  # is never more than one line.
+  def extract_files_paths(section)
+    kept = +""
+    NodeFile.each_fence_line(section) do |line, fenced|
+      next if fenced
+      break if governs_exclusion?(line)
+
+      kept << line
+    end
+    kept.scan(BACKTICK_RE).flatten.reject { |s| s.include?("\n") }.uniq
+  end
+
+  # True when a FILES_EXCLUSION_RE match on this line governs the paths on
+  # it rather than merely annotating one (D19).
+  def governs_exclusion?(line)
+    match = line.match(FILES_EXCLUSION_RE)
+    return false unless match
+
+    first_backtick = line.index("`")
+    first_backtick.nil? || match.begin(0) < first_backtick
+  end
+
+  def files_heading?(heading)
+    stripped = heading.to_s.sub(/\A#+\s*/, "")
+    first_token = stripped.split(/\s+/, 2).first.to_s.sub(/[^A-Za-z]+\z/, "")
+    return false unless first_token.casecmp?("Files")
+
+    !heading.to_s.match?(FILES_NEGATION_RE)
+  end
+
+  # The S\d+ tokens of a file's headings, in heading order, taking a
+  # heading only when it owns at least one table data row (D5) - the same
+  # table-owning rule WorkGraphValidator.has_valid_matrix? and ReportScreen
+  # already apply, reused unmodified rather than adapted, so a prose
+  # mention of an S-label never manufactures a Proven-by source (334's
+  # post-execution review defect, in the other direction).
+  def proven_by_labels(text)
+    labels = []
+    NodeFile.split_by_headings(text).each do |heading, section|
+      next unless NodeFile.table_rows(section).any?
+
+      WorkGraphValidator.heading_tokens(heading).each do |token|
+        labels << token if token.match?(PROVEN_BY_LABEL_RE)
+      end
+    end
+    labels
+  end
+end

package/scripts/lib/atomic_write.rb

@@ -0,0 +1,31 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# AtomicWrite (intent 334, n2, D19r): a sibling-temp-plus-rename write, the
+# same shape as Lock#write (scripts/lib/lock.rb) - a content write is never
+# an in-place truncate, so a crash mid-write can never leave an empty or
+# half-written target on disk. The temp file is a SIBLING in the same
+# directory as the target, never a system tmpdir, because File.rename can
+# raise EXDEV when the temp and the target live on different filesystems.
+# The temp name ends in .lock (post-execution review, non-blocking 5), the
+# same property Lock#write_temp_path documents: an orphan left by a crash
+# between the write and the rename is covered by the store's existing
+# *.lock gitignore rule rather than swept into its git add -A auto-commit.
+#
+# The renamer is injectable so the interrupted-write case (a rename that
+# raises) is testable with dependency injection, never eval or a global
+# (D19r).
+module AtomicWrite
+  module_function
+
+  def write(path, content, renamer: File.method(:rename))
+    dir = File.dirname(path)
+    temp = File.join(dir, ".#{File.basename(path)}.tmp.#{Process.pid}.#{Time.now.to_f}.#{rand(0xFFFFFF)}.lock")
+    File.write(temp, content)
+    renamer.call(temp, path)
+    true
+  rescue StandardError
+    File.delete(temp) if temp && File.exist?(temp)
+    raise
+  end
+end

package/scripts/lib/graph_edges.rb

@@ -0,0 +1,121 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# GraphEdges (intent 334, n1): the shared `needs` syntax and cycle-path check
+# (327 D2r-D4r, D12r). Parses a "## Graph" section's edge lines into a node
+# set and an edge map, the one parser an intent's graph.md and a roadmap's
+# own ## Graph section both use unchanged (C1, fold A5): the same list-item
+# grammar, the same root keyword, the same cycle walk. Deliberately loose
+# about what an id looks like - a roadmap id is numeric ("334", "340a"), a
+# node id carries a kind prefix ("n1") - the kind-prefix rule belongs to
+# NodeFile and WorkGraphValidator, never here (D12r, fold A6).
+#
+# Grammar (D2r/D3r): a list item shaped "- <id> needs <target> [<target>
+# ...]", ending at end of line. The single literal target "nothing" declares
+# a root and must be the ONLY target on the line. Any line that does not
+# start with "- <token> needs" is prose and is skipped in silence. A line
+# that DOES look like an edge is held to the grammar strictly: no target at
+# all, "nothing" alongside other targets, or a target token carrying
+# sentence punctuation (a period, a colon, ...) rather than the loose
+# id-token charset, is an error naming the line, never a silently
+# mis-parsed edge or an invented node (fold A7).
+#
+# Pure and side-effect-free; never raises across the boundary, matching the
+# Result-hash convention every library in scripts/lib/ follows.
+module GraphEdges
+  module_function
+
+  EDGE_LEAD_RE = /\A-\s*(\S+)\s+needs\b(.*)\z/.freeze
+  TOKEN_RE = /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/.freeze
+  ROOT_TARGET = "nothing"
+
+  # {nodes:, edges:, errors:} - nodes is the declared ids together with every
+  # id any edge targets (fold A5), in first-seen order; edges maps a declared
+  # id to its target ids (empty for a root); errors names each malformed
+  # edge-shaped line. Prose lines contribute nothing and raise nothing.
+  def parse(section_text)
+    declared_order = []
+    edges = {}
+    targeted = []
+    errors = []
+
+    section_text.to_s.each_line do |raw_line|
+      line = raw_line.chomp("\n").chomp("\r")
+      stripped = line.strip
+      next if stripped.empty?
+
+      m = stripped.match(EDGE_LEAD_RE)
+      next unless m
+
+      id = m[1]
+      raw_targets = m[2].to_s.strip.split(/\s+/)
+
+      if raw_targets.empty?
+        errors << "malformed edge line, no target: #{stripped.inspect}"
+        next
+      end
+
+      if raw_targets.include?(ROOT_TARGET) && raw_targets.length > 1
+        errors << "root target #{ROOT_TARGET.inspect} mixed with a real target, root must be the only target: #{stripped.inspect}"
+        next
+      end
+
+      bad_token = raw_targets.find { |t| t != ROOT_TARGET && !t.match?(TOKEN_RE) }
+      if bad_token
+        errors << "prose tail after targets: #{stripped.inspect}"
+        next
+      end
+
+      if edges.key?(id)
+        errors << "duplicate node declaration for #{id.inspect}: #{stripped.inspect}"
+        next
+      end
+
+      targets = raw_targets == [ROOT_TARGET] ? [] : raw_targets
+      declared_order << id
+      edges[id] = targets
+      targeted.concat(targets)
+    end
+
+    nodes = declared_order.dup
+    targeted.each { |t| nodes << t unless nodes.include?(t) }
+
+    { nodes: nodes, edges: edges, errors: errors }
+  end
+
+  # The cycle as a path with the entry id repeated (D4r), or nil when the
+  # graph is acyclic. A node reachable by two distinct paths (a diamond) is
+  # never mistaken for a cycle: once a node's whole subtree is walked clean
+  # it is marked visited and never re-examined.
+  def cycle(edges)
+    visiting = {}
+    visited = {}
+    path = []
+
+    edges.each_key do |node|
+      next if visited[node]
+      found = walk(node, edges, visiting, visited, path)
+      return found if found
+    end
+    nil
+  end
+
+  def walk(node, edges, visiting, visited, path)
+    if visiting[node]
+      idx = path.index(node)
+      return path[idx..] + [node]
+    end
+    return nil if visited[node]
+
+    visiting[node] = true
+    path.push(node)
+    (edges[node] || []).each do |target|
+      found = walk(target, edges, visiting, visited, path)
+      return found if found
+    end
+    path.pop
+    visiting.delete(node)
+    visited[node] = true
+    nil
+  end
+end

package/scripts/lib/graph_file.rb

@@ -0,0 +1,246 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "graph_edges"
+require_relative "atomic_write"
+
+# GraphFile (intent 334, n2): the four graph.md sections (## Goal,
+# ## Decisions, ## Graph, ## Status), the verify:-none directive, and the two
+# writers - write_status and append_decision. Both writers refuse a cyclic
+# graph and both go through AtomicWrite (fold D19r). Fence-aware everywhere a
+# heading is located, so a fenced example carrying a fake "## " line never
+# splits or ends a real section (fold A8's sibling concern, applied to
+# section boundaries rather than edge lines).
+module GraphFile
+  module_function
+
+  FENCE_LINE_RE = /\A\s{0,3}(`{3,}|~{3,})/.freeze
+  DIRECTIVE_RE = /\A-\s*verify:\s*none(?:\s+reason=(.*))?\z/i.freeze
+
+  # {ok:, goal:, decisions:, graph:, status:, verify:, errors:}. `graph` is
+  # GraphEdges.parse's own Result hash, over the Graph section text with any
+  # verify:-none directive line stripped first (fold A8). A missing ## Graph
+  # section, or one that declares no nodes, is an error naming which (fold
+  # A10).
+  def parse(path)
+    return failure(["graph file not found: #{path}"]) unless File.exist?(path)
+
+    content = File.read(path)
+    goal = section_body(content, "## Goal")
+    decisions = section_body(content, "## Decisions")
+    graph_section = section_body(content, "## Graph")
+    status = section_body(content, "## Status")
+
+    errors = []
+    if graph_section.nil?
+      errors << "missing ## Graph section"
+      return { ok: false, goal: goal, decisions: decisions, graph: nil, status: status, verify: nil, errors: errors }
+    end
+
+    directive, directive_errors, remaining = extract_verify_directive(graph_section)
+    errors.concat(directive_errors)
+
+    parsed_graph = GraphEdges.parse(strip_fenced_blocks(remaining))
+    errors.concat(parsed_graph[:errors])
+    errors << "## Graph declares no nodes" if parsed_graph[:nodes].empty?
+
+    { ok: errors.empty?, goal: goal, decisions: decisions, graph: parsed_graph, status: status, verify: directive, errors: errors }
+  end
+
+  def failure(errors)
+    { ok: false, goal: nil, decisions: nil, graph: nil, status: nil, verify: nil, errors: errors }
+  end
+
+  # Rows shaped {node:, state:, detail:} parsed back from the ## Status
+  # table (D8r's round-trip guarantee).
+  def status_rows(path)
+    parsed = parse(path)
+    rows_from_table(parsed[:status])
+  end
+
+  # Replace the whole ## Status section with rows, creating the section if
+  # absent. Refuses a cyclic graph (D8r); goes through AtomicWrite (D19r).
+  def write_status(path, rows, renamer: File.method(:rename))
+    guard = refuse_if_cyclic(path)
+    return guard if guard
+
+    content = File.read(path)
+    new_content = replace_or_append_section(content, "## Status", render_status_table(rows))
+    AtomicWrite.write(path, new_content, renamer: renamer)
+    { ok: true, errors: [] }
+  end
+
+  # Append one answered decision as a list item to ## Decisions (C26),
+  # leaving every other section byte-identical. Refuses a cyclic graph.
+  def append_decision(path, text, renamer: File.method(:rename))
+    guard = refuse_if_cyclic(path)
+    return guard if guard
+
+    content = File.read(path)
+    bounds = section_bounds(content, "## Decisions")
+    return { ok: false, errors: ["missing ## Decisions section"] } unless bounds
+
+    start_idx, end_idx = bounds
+    heading_line_end = line_end(content, start_idx)
+    body = content[heading_line_end...end_idx]
+    trimmed = body.rstrip
+    trailing = body[trimmed.length..]
+    new_body = trimmed.empty? ? "- #{text}#{trailing}" : "#{trimmed}\n- #{text}#{trailing}"
+    new_content = content[0...heading_line_end] + new_body + content[end_idx..]
+    AtomicWrite.write(path, new_content, renamer: renamer)
+    { ok: true, errors: [] }
+  end
+
+  def refuse_if_cyclic(path)
+    parsed = parse(path)
+    return { ok: false, errors: parsed[:errors] } if parsed[:graph].nil?
+
+    cyc = GraphEdges.cycle(parsed[:graph][:edges])
+    return { ok: false, errors: ["cyclic graph, refusing to write: #{cyc.join(' > ')}"] } if cyc
+
+    nil
+  end
+
+  # --- verify: none directive --------------------------------------------------
+
+  def extract_verify_directive(graph_section)
+    return [nil, [], graph_section] if graph_section.nil?
+
+    reason = nil
+    present = false
+    errors = []
+    remaining_lines = []
+
+    graph_section.each_line do |line|
+      stripped = line.strip
+      m = stripped.match(DIRECTIVE_RE)
+      if m
+        present = true
+        captured = m[1].to_s.strip
+        if captured.empty?
+          errors << "verify: none requires reason=<text>: #{stripped.inspect}"
+        else
+          reason = captured
+        end
+      else
+        remaining_lines << line
+      end
+    end
+
+    directive = present ? { reason: reason } : nil
+    [directive, errors, remaining_lines.join]
+  end
+
+  # D18: drop every fenced line from `text`, so a fenced example edge inside a
+  # hand-written graph.md or roadmap ## Graph section is never handed to
+  # GraphEdges as real edge text. Non-fenced lines pass through unchanged.
+  def strip_fenced_blocks(text)
+    lines = []
+    each_fence_line(text) { |line, fenced| lines << line unless fenced }
+    lines.join
+  end
+
+  # --- fence-aware section location ---------------------------------------------
+
+  def each_fence_line(text)
+    return enum_for(:each_fence_line, text) unless block_given?
+
+    marker = nil
+    text.to_s.each_line do |line|
+      if marker
+        yield line, true
+        m = line.match(FENCE_LINE_RE)
+        next unless m && m[1][0] == marker[0] && m[1].length >= marker[1]
+        next unless line.sub(FENCE_LINE_RE, "").strip.empty?
+
+        marker = nil
+      else
+        m = line.match(FENCE_LINE_RE)
+        if m
+          marker = [m[1][0], m[1].length]
+          yield line, true
+        else
+          yield line, false
+        end
+      end
+    end
+  end
+
+  # [start_of_heading_line, start_of_next_top_level_heading_or_EOF] byte
+  # offsets for the FIRST line, outside any fence, whose stripped text
+  # exactly equals heading_text. nil when no such line exists.
+  def section_bounds(content, heading_text)
+    offset = 0
+    heading_start = nil
+
+    each_fence_line(content) do |line, fenced|
+      if !fenced && heading_start.nil? && line.strip == heading_text
+        heading_start = offset
+      elsif !fenced && heading_start && offset > heading_start && line.match?(/\A##[^#]/)
+        return [heading_start, offset]
+      end
+      offset += line.length
+    end
+
+    heading_start ? [heading_start, offset] : nil
+  end
+
+  def section_body(content, heading_text)
+    bounds = section_bounds(content, heading_text)
+    return nil unless bounds
+
+    start_idx, end_idx = bounds
+    content[(line_end(content, start_idx))...end_idx].to_s
+  end
+
+  def line_end(content, start_idx)
+    idx = content.index("\n", start_idx)
+    idx ? idx + 1 : content.length
+  end
+
+  def replace_or_append_section(content, heading_text, body_text)
+    rendered_body = body_text.to_s
+    rendered_body += "\n" unless rendered_body.end_with?("\n")
+    section = "#{heading_text}\n#{rendered_body}"
+
+    bounds = section_bounds(content, heading_text)
+    if bounds
+      start_idx, end_idx = bounds
+      tail = content[end_idx..].to_s
+      section += "\n" unless tail.empty?
+      content[0...start_idx] + section + tail
+    else
+      head = content.dup
+      head += "\n" unless head.end_with?("\n")
+      head += "\n" unless head.end_with?("\n\n")
+      head + section
+    end
+  end
+
+  # --- table rendering and reading -----------------------------------------------
+
+  def render_status_table(rows)
+    lines = ["| Node | State | Detail |", "| --- | --- | --- |"]
+    rows.each { |r| lines << "| #{r[:node]} | #{r[:state]} | #{r[:detail]} |" }
+    "#{lines.join("\n")}\n"
+  end
+
+  def rows_from_table(text)
+    return [] if text.nil?
+
+    lines = []
+    each_fence_line(text) do |line, fenced|
+      next if fenced
+
+      stripped = line.strip
+      lines << stripped if stripped.start_with?("|")
+    end
+    sep_idx = lines.index { |l| l.match?(/\A\|[\s:|-]+\|?\z/) }
+    return [] unless sep_idx
+
+    lines[(sep_idx + 1)..].map do |l|
+      cells = l.split("|", -1).map(&:strip)[1..-2].to_a
+      { node: cells[0], state: cells[1], detail: cells[2] }
+    end
+  end
+end