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

package/scripts/lib/roadmap_queue.rb

@@ -4,6 +4,8 @@
 require "time"
 require "json"
 require_relative "roadmap_savepoint"
+require_relative "graph_file"
+require_relative "graph_edges"
 
 # 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
@@ -98,6 +100,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 =
@@ -129,7 +140,28 @@ 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)),
+      graph_edges: parse_roadmap_graph(text),
+    }
+  end
+
+  # D15: an exact "## Graph" heading line only, never a prefix - a live
+  # roadmap can carry "## Graph (2026-09-01, superseded by ...)", which
+  # GraphFile.section_body already treats as a non-match because it locates
+  # a section by an exact stripped-line comparison. A section that yields no
+  # real edge lines (GraphEdges.parse finds zero nodes) is treated the same
+  # as no section at all: the fallback to wave order, both silent (D15).
+  # Fence-aware (D18): a fenced example edge line is never read as real.
+  def parse_roadmap_graph(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
 
   def parse_waves(waves_body)
@@ -241,9 +273,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) }
@@ -267,12 +307,130 @@ 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] = [] }
+
+    topological_layers(edges).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
+
+  # Topological layers of `edges` ({id => [needs...]}): layer one is every
+  # id needing nothing, layer k is every id all of whose needs sit in layers
+  # below k. Never called on a cyclic graph (the caller checks first), so no
+  # cycle guard is needed here.
+  def topological_layers(edges)
+    nodes = edges.keys.dup
+    edges.each_value { |targets| (targets || []).each { |t| nodes << t unless nodes.include?(t) } }
+
+    layer = {}
+    assign = nil
+    assign = lambda do |node|
+      next layer[node] if layer.key?(node)
+
+      needs = edges[node] || []
+      layer[node] = needs.empty? ? 1 : 1 + needs.map { |t| assign.call(t) }.max
+    end
+    nodes.each { |n| assign.call(n) }
+
+    grouped = Hash.new { |h, k| h[k] = [] }
+    layer.each { |n, l| grouped[l] << n }
+    grouped.keys.sort.map { |l| grouped[l].sort }
+  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_savepoint.rb

@@ -3,6 +3,7 @@
 
 require "time"
 require "fileutils"
+require_relative "guarded_append"
 
 # RoadmapSavepoint - the roadmap's machine counterpart to its human `## Log` (intent 134).
 #
@@ -95,17 +96,37 @@ module RoadmapSavepoint
   # recorded (no-op). Creates the paired ledger file (and its directory) lazily. Raises
   # ArgumentError when `event` is outside the controlled vocabulary. Returns true when a line
   # was written, false on a dedup no-op.
-  def append(roadmap_path, event, detail, now: Time.now)
+  #
+  # Intent 335 (spec D14): the dedup check moves INSIDE one GuardedAppend hold, which makes
+  # "is this pair already recorded" and "append it" atomic against a second writer without
+  # changing what this method returns. `strict: false` keeps this ledger's existing
+  # flock-less-filesystem fallback exactly as it was before the guard existed (spec D12a): a
+  # single O_APPEND write still lands whole there, so this ledger never refuses on such a
+  # filesystem, unlike a strict transition append elsewhere in 335. `guard:` is the sole thing
+  # this module takes from 335 (spec D14: "RoadmapSavepoint takes GuardedAppend and nothing else");
+  # `flock:`/`sleeper:` pass straight through as GuardedAppend test seams, never read from an
+  # environment variable. The directory is created BEFORE the guard is called (spec D12b): the
+  # guard's own File.open would raise Errno::ENOENT on a missing parent, which must propagate as
+  # itself rather than be mistaken for lock contention.
+  def append(roadmap_path, event, detail, now: Time.now, guard: GuardedAppend, **guard_opts)
     unless EVENTS.include?(event)
       raise ArgumentError, "event must be one of #{EVENTS.join(', ')}, got #{event.inspect}"
     end
 
     ledger_path = ledger_path_for(roadmap_path)
-    return false if recorded_pairs(ledger_path).include?([event, detail])
-
     FileUtils.mkdir_p(File.dirname(ledger_path))
-    File.open(ledger_path, "a") { |io| io.write(format_line(now, event, detail)) }
-    true
+
+    pair = [event, detail]
+    written = false
+    guard.call(ledger_path, strict: false, **guard_opts) do |content|
+      if content.each_line.filter_map { |line| parse_pair(line) }.include?(pair)
+        nil
+      else
+        written = true
+        format_line(now, event, detail)
+      end
+    end
+    written
   end
 
   def format_line(time, event, detail)

package/scripts/lib/savepoint.rb

@@ -23,6 +23,36 @@ module Savepoint
   # (<id>--<slug>.md) is never sentineled; it is born complete.
   PLACEHOLDER_SENTINEL = "<!-- plastic:placeholder -->"
 
+  # --- Node-graph transition subject vocabulary (intent 335, spec D17) -------
+  #
+  # Owned HERE, not on NodeLedger, because test/savepoint_split_test.rb:57 pins
+  # savepoint.rb to loading no other project file: NodeLedger requires this
+  # file and reuses these three names rather than duplicating them, so the
+  # dependency runs one way only. Intent 334 (G1) mints node ids and must
+  # agree with NODE_SUBJECT_RE: it is the single seam for the node id shape.
+
+  # The literal subject token for an intent-scope transition line ("Intent
+  # needs_decision question=..."), as opposed to a node-scope line.
+  INTENT_SUBJECT = "Intent"
+
+  # A node id: one or two lowercase letters (the node's kind prefix, e.g. "n"
+  # for work, "v" for verify) followed by digits.
+  NODE_SUBJECT_RE = /\A[a-z]{1,2}\d+\z/.freeze
+
+  # True iff a raw savepoint ledger line's subject (field 2, split on
+  # /\s{2,}/) is a transition candidate: the literal Intent token or a node
+  # id. A stage line ("How  checklist.md created") or a Lock takeover audit
+  # line never matches, by construction (spec Acceptance Criteria: "no stage
+  # token this tree writes collides with Intent or with the node id
+  # pattern").
+  def self.transition_candidate?(line)
+    parts = line.to_s.split(/\s{2,}/)
+    return false unless parts.length >= 2
+
+    subject = parts[1]
+    subject == INTENT_SUBJECT || subject.match?(NODE_SUBJECT_RE)
+  end
+
   def self.intent_file(intent_dir)
     dir_name = File.basename(intent_dir)
     "#{intent_dir}/#{dir_name}.md"
@@ -57,22 +87,47 @@ module Savepoint
     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|
+  # True iff DIR_NAME (actions/ or nodes/) holds AT LEAST ONE real *.md file: non-empty,
+  # first line not the placeholder sentinel. A `.gitkeep` (no .md extension) never counts.
+  # Pure and side-effect-free; fail-open (a missing dir globs to nothing, never raises).
+  def self.has_real_files_in?(dir_name, intent_dir)
+    Dir.glob("#{intent_dir}/#{dir_name}/*.md").any? do |f|
       File.file?(f) && File.size(f) > 0 && stage_file_present?(f)
     end
   rescue StandardError
     false
   end
 
+  # True iff the intent has at least one real action file, whether delivered as
+  # legacy actions/*.md or as a node graph's nodes/*.md (intent 334, G1, D10r):
+  # an intent delivered as nodes is exactly as real as one delivered as
+  # actions, so doctor and the exec-stage gate never report a backfill gap on
+  # a fully delivered node-graph intent. Checks actions/ first (the common
+  # path today), falling through to nodes/ only when actions/ has nothing.
+  def self.has_real_action?(intent_dir)
+    has_real_files_in?("actions", intent_dir) || has_real_files_in?("nodes", intent_dir)
+  rescue StandardError
+    false
+  end
+
+  # Intent 336 (G3, D13): a real graph.md is 327 D41's replacement for
+  # plan.md/checklist.md on the common path, so a node-shaped intent is
+  # judged on graph.md and nodes/ alone, whether or not spec.md is real - the
+  # graph IS the spec under D41. Checked using only this file's own
+  # primitives (stage_file_present?, has_real_files_in?), because
+  # test/savepoint_split_test.rb pins this file to loading no other project
+  # file and no YAML: GraphFile/NodeFile/ReadySet are never required here. An
+  # intent with no real graph.md (or a sentinel-placeholder one,
+  # stage_file_present? already reads that as absent) derives exactly what it
+  # derived before this intent.
   def self.derive_stage(intent_dir)
     return "done" if stage_file_present?("#{intent_dir}/outcome.md")
+
+    if stage_file_present?("#{intent_dir}/graph.md")
+      return "exec" if has_real_files_in?("nodes", intent_dir)
+      return "how"
+    end
+
     if stage_file_present?("#{intent_dir}/plan.md") &&
        has_real_action?(intent_dir) &&
        stage_file_present?("#{intent_dir}/checklist.md")
@@ -87,19 +142,49 @@ module Savepoint
     files = []
     ifile = File.basename(intent_file(intent_dir))
     files << ifile if File.exist?("#{intent_dir}/#{ifile}")
-    ["spec.md", "plan.md", "checklist.md", "outcome.md"].each do |f|
+    ["spec.md", "graph.md", "plan.md", "checklist.md", "outcome.md"].each do |f|
       files << f if stage_file_present?("#{intent_dir}/#{f}")
     end
-    files << "actions/" if has_real_action?(intent_dir)
+    # Name the directory that actually exists (fold B3): a nodes-only intent
+    # must never claim the literal "actions/" artifact it does not have.
+    # Checks actions/ first, matching D15r's read order.
+    if has_real_files_in?("actions", intent_dir)
+      files << "actions/"
+    elsif has_real_files_in?("nodes", intent_dir)
+      files << "nodes/"
+    end
     files
   end
 
   def self.missing_for_stage(stage, intent_dir = nil)
     ifile = intent_dir ? File.basename(intent_file(intent_dir)) : "intent.md"
+    # A How-stage intent that already started a nodes/ directory is named
+    # accordingly, so the next-step hint never tells a node-graph intent to
+    # go make an actions/ directory it will never use (fold B3). Mirrors
+    # has_real_files_in?'s actions-first order and its real-file requirement
+    # (post-execution review, non-blocking 4): an intent carrying real files
+    # in both directories, or a real actions/ file beside an empty or
+    # .gitkeep-only nodes/, is named actions/, never nodes/.
+    action_label = if intent_dir && has_real_files_in?("actions", intent_dir)
+      "actions/"
+    elsif intent_dir && has_real_files_in?("nodes", intent_dir)
+      "nodes/"
+    else
+      "actions/"
+    end
     case stage
     when "what" then [ifile]
     when "why" then ["spec.md"]
-    when "how" then ["plan.md", "actions/", "checklist.md"]
+    when "how"
+      # A node-shaped How intent (a real graph.md already) is named after its
+      # own two artifacts, never the three D41 removed from its path (fold
+      # B3, extended by 336 D13): checked via stage_file_present? alone, the
+      # same primitive derive_stage itself uses.
+      if intent_dir && stage_file_present?("#{intent_dir}/graph.md")
+        ["graph.md", "nodes/"]
+      else
+        ["plan.md", action_label, "checklist.md"]
+      end
     when "exec" then ["outcome.md"]
     else []
     end
@@ -258,6 +343,17 @@ module Savepoint
   # A Plastic 1.x ledger may carry a `Tier  <value>` line after the spec.md
   # milestone (removed in 2.0, intent 304); a rebuild drops it, and the phantom
   # detector ignores it, so a 1.x store reads clean.
+  #
+  # Every transition line (intent 335, spec D13) is preserved VERBATIM, in its
+  # original relative order, after the reconstructed stage skeleton. It is
+  # never dropped and never refused: a transition line's evidence fields
+  # (`holder=`, `expires=`, `gates=`, ...) have no file-mtime analog to
+  # reconstruct from, so refusing instead of preserving would make this method
+  # destroy the graph's only status on every intent that carries one. Relative
+  # order BETWEEN a stage line and a transition line is not preserved (safe:
+  # status is computed per subject, and the two families share no subject);
+  # relative order WITHIN the transition lines is preserved, which is what
+  # "last line per subject in file order" depends on.
   def self.rebuild_savepoint(intent_dir)
     ordered = [
       File.basename(intent_file(intent_dir)),
@@ -271,7 +367,18 @@ module Savepoint
       stamp = File.mtime(path).utc.iso8601
       ["#{stamp}  #{stage}  #{milestone}\n"]
     end
-    File.write(File.join(intent_dir, SAVEPOINT_FILE), lines.join)
+
+    savepoint_path = File.join(intent_dir, SAVEPOINT_FILE)
+    if File.exist?(savepoint_path)
+      # #scrub before scanning (post-execution review row 7.8), the same way
+      # NodeLedger.entries does (matrix 2.44): a stray non-UTF-8 byte anywhere
+      # in the ledger must not raise out of the one repair tool three doctor
+      # fix hints and maintenance-run --tool rebuild-savepoint point at.
+      transition_lines = File.read(savepoint_path).scrub.each_line.select { |raw| transition_candidate?(raw) }
+      lines += transition_lines.map { |raw| raw.end_with?("\n") ? raw : "#{raw}\n" }
+    end
+
+    File.write(savepoint_path, lines.join)
     lines.length
   end
 
@@ -320,6 +427,10 @@ module Savepoint
     File.read(path).each_line do |raw|
       line = raw.strip
       next if line.empty?
+      # A transition line (intent 335) is never a stage phantom candidate: its
+      # own repeated-line semantics (dedup-free by design, spec D11) are
+      # NodeLedger's concern, not this detector's.
+      next if transition_candidate?(line)
       parts = line.split(/\s{2,}/)
       next if parts.length < 3
       pair = [parts[1], parts[2]]

package/scripts/lib/work_graph_validator.rb

@@ -0,0 +1,201 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "graph_file"
+require_relative "graph_edges"
+require_relative "node_file"
+require_relative "action_graph_shim"
+
+# WorkGraphValidator (intent 334, n4): the in-batch reader over one intent's
+# graph.md and nodes/ - 327's rule for budget, files, and the decision and
+# research kinds (fold A17). {ok:, missing:, errors:}, the same Result shape
+# ProjectValidator returns (fold B7). Named apart from
+# IntentValidator#validate_graph, which already exists for the KNOWLEDGE
+# graph and stays unrelated to this one under D40 (fold B9).
+#
+# Built over GraphFile, GraphEdges, and NodeFile only - never IntentValidator,
+# never ReportScreen. Every check accumulates into `errors` rather than
+# short-circuiting on the first one (fold: "the owner fixes one thing per
+# run").
+module WorkGraphValidator
+  module_function
+
+  def validate(intent_dir)
+    missing = []
+    errors = []
+
+    graph_path = File.join(intent_dir, "graph.md")
+    parsed = GraphFile.parse(graph_path)
+    errors.concat(parsed[:errors])
+
+    graph = parsed[:graph]
+    if graph.nil?
+      # G9 (intent 342, D6/D7/D12): a legacy intent that never got a
+      # graph.md still reads as a valid work graph, structurally, through
+      # the backward shim - but only when graph.md is genuinely absent.
+      # A graph.md that exists but is malformed (no "## Graph" section)
+      # must never fall through to the synthetic chain and hide its own
+      # error (D12's whole point). The fresh error list here is
+      # deliberate: `errors` above already holds the not-found error from
+      # `parsed[:errors]`, and reusing it would return ok: false for every
+      # legacy intent in the store.
+      if !File.exist?(graph_path) && ActionGraphShim.shape(intent_dir) == :actions
+        return validate_actions_shape(intent_dir)
+      end
+
+      missing << "graph.md ## Graph section"
+      return { ok: false, missing: missing, errors: errors }
+    end
+
+    nodes = graph[:nodes]
+    edges = graph[:edges]
+    declared_ids = edges.keys
+
+    # Intent-scope dangling check: every node must be declared with its own
+    # needs-line here (unlike a roadmap, which may have undeclared roots -
+    # that reconciliation is G4's, not this validator's).
+    (nodes - declared_ids).each { |id| errors << "needs target #{id.inspect} names no declared node" }
+
+    cyc = GraphEdges.cycle(edges)
+    errors << "cyclic graph, cannot validate: #{cyc.join(' > ')}" if cyc
+
+    node_paths = Dir.glob(File.join(intent_dir, "nodes", "*.md")).sort
+    parsed_nodes = {}
+    paths_by_id = Hash.new { |h, k| h[k] = [] }
+
+    node_paths.each do |path|
+      nf = NodeFile.parse(path)
+      nf[:errors].each { |e| errors << "#{File.basename(path)}: #{e}" }
+      id = nf[:node]
+      next unless id
+
+      paths_by_id[id] << path
+      parsed_nodes[id] ||= nf
+    end
+
+    paths_by_id.each do |id, paths|
+      next unless paths.length > 1
+
+      errors << "node id #{id.inspect} claimed by more than one file: #{paths.map { |p| File.basename(p) }.join(', ')}"
+    end
+
+    declared_ids.each do |id|
+      missing << "nodes/ file for #{id}" unless parsed_nodes.key?(id)
+      errors << "declared node #{id.inspect} has no node file under nodes/" unless parsed_nodes.key?(id)
+    end
+    parsed_nodes.each_key do |id|
+      errors << "node file for #{id.inspect} exists but ## Graph declares no such node" unless declared_ids.include?(id)
+    end
+
+    work_nodes = []
+    verify_nodes = []
+
+    declared_ids.each do |id|
+      nf = parsed_nodes[id]
+      next unless nf
+
+      case nf[:kind]
+      when "verify"
+        verify_nodes << id
+        errors << "verify node #{id.inspect} has no ## Criteria" unless has_section?(nf[:body], "## Criteria")
+      when "decision"
+        errors << "decision node #{id.inspect} has no ## Question with a question" unless has_nonblank_section?(nf[:body], "## Question")
+      when "research"
+        errors << "research node #{id.inspect} has no ## Deposit" unless has_section?(nf[:body], "## Deposit")
+      when "work"
+        work_nodes << id
+        errors << "work node #{id.inspect} has no ## Steps" unless has_section?(nf[:body], "## Steps")
+        errors << "work node #{id.inspect} has no ## Proven by" unless has_section?(nf[:body], "## Proven by")
+      end
+    end
+
+    above_trivial_bar = work_nodes.length >= 2
+    if above_trivial_bar
+      verify_directive = parsed[:verify]
+      directive_ok = verify_directive && !verify_directive[:reason].to_s.empty?
+
+      unless directive_ok
+        attached = verify_nodes.select { |vid| node_touches_graph?(vid, edges) }
+        if attached.empty?
+          errors << "two or more work nodes require a verify node attached to the graph, or a verify: none reason=<text> directive"
+        end
+      end
+
+      work_nodes.each do |id|
+        nf = parsed_nodes[id]
+        next unless nf
+
+        errors << "work node #{id.inspect} has no failure-mode matrix under a heading carrying its id" unless has_valid_matrix?(id, nf[:body])
+      end
+    end
+
+    verify_nodes.each do |id|
+      next if node_touches_graph?(id, edges)
+
+      errors << "verify node #{id.inspect} exists but no edge reaches it (attach it or drop it)"
+    end
+
+    { ok: errors.empty?, missing: missing, errors: errors }
+  end
+
+  # A node "touches" the graph when some edge involves it on either side:
+  # it targets something, or something targets it. A verify node declared
+  # with "needs nothing" and targeted by nothing is fully isolated (fold
+  # A13).
+  def node_touches_graph?(id, edges)
+    (edges[id] || []).any? || edges.values.any? { |targets| targets.include?(id) }
+  end
+
+  def has_section?(body, heading_text)
+    NodeFile.split_by_headings(body.to_s).any? { |heading, _| heading.strip == heading_text }
+  end
+
+  def has_nonblank_section?(body, heading_text)
+    NodeFile.split_by_headings(body.to_s).any? { |heading, section| heading.strip == heading_text && !section.strip.empty? }
+  end
+
+  def heading_tokens(heading)
+    heading.to_s.sub(/\A#+\s*/, "").split(/[^A-Za-z0-9]+/)
+  end
+
+  # The matrix table must sit under a heading whose tokens include the
+  # node's own id, and that heading must own at least one data row (fold
+  # A1 - the same table-owning rule report_screen's resolver uses, so a
+  # node's own Proven-by cell is never "not recorded" the moment it ships).
+  def has_valid_matrix?(id, body)
+    NodeFile.split_by_headings(body.to_s).any? do |heading, section|
+      heading_tokens(heading).include?(id) && NodeFile.table_rows(section).any?
+    end
+  end
+
+  # The structural check the synthetic (actions/-only) shape gets, and
+  # nothing more (D6): at least one node, unique ids, every needs target
+  # names a declared node, acyclic. Never the kind-section rules, the
+  # failure-mode matrix bar, or the verify-attachment bar - a legacy action
+  # file labels its headings "S1", or nothing at all, and was never asked
+  # to meet a bar written for a graph authored under 327.
+  def validate_actions_shape(intent_dir)
+    errors = []
+    graph = ActionGraphShim.view(intent_dir)[:graph] || { nodes: [], edges: {}, errors: [] }
+    nodes = graph[:nodes]
+    edges = graph[:edges]
+
+    errors << "actions/ yields no nodes" if nodes.empty?
+    # D16: uniqueness is checked over the node array, not edges.keys - a
+    # Hash key set is unique by construction, so checking edges.keys can
+    # never fire.
+    errors << "duplicate node ids in synthetic chain" if nodes.uniq.length != nodes.length
+
+    # D16: every needs target is checked against the declared node list,
+    # not the node list against its own key set (nodes - edges.keys, which
+    # can never differ since the builder mints edges.keys from nodes).
+    (edges.values.flatten.uniq - nodes).each do |id|
+      errors << "needs target #{id.inspect} names no declared node"
+    end
+
+    cyc = GraphEdges.cycle(edges)
+    errors << "cyclic graph, cannot validate: #{cyc.join(' > ')}" if cyc
+
+    { ok: errors.empty?, missing: [], errors: errors }
+  end
+end