@zalom/plastic 2.0.0-alpha.9 → 2.0.1

package/scripts/ready-set

@@ -0,0 +1,126 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# ready-set - the CLI over ReadySet (intent 336, G3). No computed field this
+# intent adds ships without a script that reads it (327 D18, C19): prints the
+# ready order, the blockers for every unready node, the batches, and every
+# maximal-length critical path; emits JSON for a caller like the runner (G7).
+#
+# Usage:
+#   ready-set <intent_dir> [--json] [--ranker finish-first|critical-path]
+#
+# Exit codes (matching scripts/validate-work-graph's shape):
+#   0 - printed (or emitted as JSON)
+#   1 - the graph is invalid (missing, cyclic, or a malformed node file)
+#   2 - usage: not an intent directory, or an unknown --ranker value
+
+require "json"
+require_relative "lib/ready_set"
+require_relative "lib/savepoint"
+
+module ReadySetCli
+  module_function
+
+  RANKERS = {
+    "finish-first" => -> { ReadySet::FinishFirstRanker.new },
+    "critical-path" => -> { ReadySet::CriticalPathRanker.new },
+  }.freeze
+
+  def usage
+    warn "Usage: ready-set <intent_dir> [--json] [--ranker #{RANKERS.keys.join('|')}]"
+  end
+
+  def intent_directory?(dir)
+    dir && File.directory?(dir) && File.exist?(Savepoint.intent_file(dir))
+  end
+
+  def main(argv)
+    args = argv.dup
+    json = !!args.delete("--json")
+
+    ranker_name = nil
+    if (i = args.index("--ranker"))
+      ranker_name = args[i + 1]
+      args.slice!(i, 2)
+    end
+
+    intent_dir_arg = args.shift
+    unless intent_directory?(intent_dir_arg && File.expand_path(intent_dir_arg))
+      warn "ready-set: #{intent_dir_arg.inspect} is not an intent directory"
+      usage
+      return 2
+    end
+    intent_dir = File.expand_path(intent_dir_arg)
+
+    ranker = nil
+    if ranker_name
+      factory = RANKERS[ranker_name]
+      unless factory
+        warn "ready-set: unknown ranker #{ranker_name.inspect} (use #{RANKERS.keys.join(', ')})"
+        return 2
+      end
+      ranker = factory.call
+    end
+
+    analysis = ReadySet.analyze(intent_dir, ranker: ranker)
+    unless analysis[:ok]
+      warn "ready-set: #{analysis[:errors].join('; ')}"
+      return 1
+    end
+
+    if json
+      puts JSON.pretty_generate(json_payload(analysis))
+    else
+      print_report(analysis)
+    end
+    0
+  end
+
+  def json_payload(analysis)
+    unready = analysis[:nodes].reject { |_, v| v[:ready] }
+    {
+      "ready" => analysis[:ranked_ready].map { |r| r[:id] },
+      "ranker" => analysis[:ranker_name],
+      "batches" => analysis[:batches],
+      "critical_path" => analysis[:critical_path],
+      "paths" => analysis[:paths],
+      "hops" => analysis[:hops],
+      "max_paths_total" => analysis[:max_paths_total],
+      "blockers" => unready.transform_values { |v| v[:blockers] },
+      "errors" => analysis[:errors],
+    }
+  end
+
+  def print_report(analysis)
+    unready = analysis[:nodes].reject { |_, v| v[:ready] }
+
+    puts "Ranker: #{analysis[:ranker_name]}"
+    puts
+    puts "Ready (#{analysis[:ranked_ready].length}):"
+    if analysis[:ranked_ready].empty?
+      puts "  (none)"
+    else
+      analysis[:ranked_ready].each { |r| puts "  #{r[:id]}" }
+    end
+    puts
+    puts "Blockers:"
+    if unready.empty?
+      puts "  (none)"
+    else
+      unready.each do |id, view|
+        puts "  #{id}:"
+        view[:blockers].each { |b| puts "    - #{b}" }
+      end
+    end
+    puts
+    puts "Batches:"
+    analysis[:batches].each_with_index { |batch, i| puts "  #{i + 1}: #{batch.join(', ')}" }
+    puts
+    puts "Critical path (#{analysis[:hops]} hops): #{(analysis[:critical_path] || []).join(' > ')}"
+    puts "Every maximal-length path (#{analysis[:max_paths_total]} total, #{analysis[:paths].length} shown):"
+    analysis[:paths].each { |p| puts "  #{p.join(' > ')}" }
+  end
+end
+
+exit(ReadySetCli.main(ARGV)) if $PROGRAM_NAME == __FILE__

package/scripts/release-check

@@ -0,0 +1,123 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# release-check - deterministic CLI over ReleaseGuard (intent 347).
+#
+# Guards a tagged publish before the workflow ever reaches `npm publish`:
+# the pushed tag must equal `v` plus the version in package.json, the three
+# repo version files must agree, and the runner's npm must meet the 11.5.1
+# floor npm requires for OIDC trusted publishing. Writes the derived
+# dist-tag and version to $GITHUB_OUTPUT, so the alpha/beta/latest rule has
+# exactly one implementation, ReleaseGuard.dist_tag, shared with the test
+# suite.
+#
+# Usage:
+#   release-check (--tag <tag> | --branch <branch>) --npm-version <version>
+#                  [--github-output <path>] [--root <dir>]
+#
+# Exit codes: 0 (clean), 1 (violations; reported on stderr, one per line,
+# each naming the specific thing that is wrong), 2 (usage).
+
+require "json"
+
+require_relative "lib/release_guard"
+
+NPM_FLOOR = [11, 5, 1].freeze
+KNOWN_FLAGS = %w[--tag --branch --npm-version --github-output --root].freeze
+
+def usage
+  warn "usage: release-check (--tag <tag> | --branch <branch>) --npm-version <version> [--github-output <path>] [--root <dir>]"
+  exit 2
+end
+
+def parse_args(argv)
+  opts = {}
+  i = 0
+  while i < argv.length
+    flag = argv[i]
+    usage unless KNOWN_FLAGS.include?(flag)
+
+    value = argv[i + 1]
+    usage if value.nil?
+
+    opts[flag] = value
+    i += 2
+  end
+  opts
+end
+
+def read_version(path)
+  JSON.parse(File.read(path))["version"]
+rescue Errno::ENOENT, JSON::ParserError
+  nil
+end
+
+opts = parse_args(ARGV)
+usage unless (opts["--tag"] || opts["--branch"]) && opts["--npm-version"]
+
+root = opts["--root"] ? File.expand_path(opts["--root"]) : File.expand_path("..", __dir__)
+package_json_path = File.join(root, "package.json")
+plugin_json_path = File.join(root, ".claude-plugin", "plugin.json")
+marketplace_json_path = File.join(root, ".claude-plugin", "marketplace.json")
+
+violations = []
+
+canonical_version = read_version(package_json_path)
+violations << "could not read a version from #{package_json_path}" if canonical_version.nil?
+
+branch = opts["--branch"]
+dist_tag = nil
+
+if canonical_version
+  expected_tag = "v#{canonical_version}"
+  tag = opts.fetch("--tag", expected_tag).sub(%r{\Arefs/tags/}, "")
+  if tag != expected_tag
+    violations << "tag #{tag} does not match package.json version #{canonical_version} (expected #{expected_tag})"
+  end
+
+  dist_tag = ReleaseGuard.dist_tag(canonical_version)
+  if branch && ReleaseGuard::CHANNELS[branch] != dist_tag
+    violations << "branch #{branch} publishes #{ReleaseGuard::CHANNELS[branch] || "nothing"}, and version #{canonical_version} is #{dist_tag}"
+  end
+  stable = dist_tag == "latest"
+
+  result = ReleaseGuard.check(
+    package_json: package_json_path,
+    plugin_json: plugin_json_path,
+    marketplace_json: marketplace_json_path,
+    stable: stable
+  )
+
+  unless result.ok?
+    result.mismatches.each do |file|
+      violations << "version file #{file} does not agree with package.json (#{canonical_version})"
+    end
+    if stable && result.prerelease_suffix
+      violations << "stable cut #{canonical_version} carries the pre-release suffix -#{result.prerelease_suffix}"
+    end
+  end
+end
+
+npm_version = opts["--npm-version"].to_s.strip
+if npm_version.empty? || !npm_version.match?(/\A\d+(\.\d+)*\z/)
+  violations << "npm --version reported #{opts["--npm-version"].inspect}, which is empty or not numeric"
+elsif (npm_version.split(".").map(&:to_i) <=> NPM_FLOOR) < 0
+  violations << "npm #{npm_version} is below the 11.5.1 floor OIDC trusted publishing requires"
+end
+
+if violations.empty?
+  if opts["--github-output"]
+    File.open(opts["--github-output"], "a") do |f|
+      f.puts "version=#{canonical_version}"
+      f.puts "dist_tag=#{dist_tag}"
+      f.puts "tag=#{tag}"
+    end
+  end
+  puts "OK: tag #{tag}, version #{canonical_version}, dist-tag #{dist_tag}"
+  exit 0
+end
+
+warn "VIOLATIONS:"
+violations.each { |v| warn "- #{v}" }
+exit 1

package/scripts/report-screen

@@ -2,15 +2,22 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-# report-screen - the three delivery-report screens (intent 317): mid-delivery
-# state, post-delivery delivered, and delay. Each fills from the record via
+# report-screen - the pre-delivery plan (intent 331b), the four delivery
+# reports: mid-delivery state, post-delivery delivered, and delay (intent
+# 317), plus session, the whole of one session's delivered work followed by
+# the roster (intent 330). Each fills from the record via
 # scripts/lib/report_screen.rb; no number here is written by eye.
 #
 # Usage:
+#   report-screen plan <intent_dir> [--ansi]
 #   report-screen state <intent_dir> [--changed "<text>"] [--ansi]
 #   report-screen state --all <store_root> [--changed "<text>"] [--ansi]
-#   report-screen delivered <intent_dir> [--ansi]
+#   report-screen delivered <intent_dir> [--ansi] [--repo <dir>]
 #   report-screen delay <intent_dir> [--ansi]
+#   report-screen session <tier_root> [--session <id>] [--since <iso>]
+#                                     [--ledger-root <dir>] [--ansi]
+#   report-screen roadmap <roadmap.md> plan|state|delivered [--ansi] [--store-root <dir>]
+#   report-screen archive <store_root> [--ansi]
 #
 # --ansi delegates to ScreenPaint (intent 317a, D1), the parser/re-layouter
 # in the shared TUI core. Selection is by capability, never by harness:
@@ -23,24 +30,93 @@
 #   2 - usage error, or the path/store is not what the verb expects (one line
 #       on stderr, stdout empty)
 
+require "yaml"
+require "shellwords"
 require_relative "lib/report_screen"
 require_relative "lib/intent_screen"
 require_relative "lib/screen_paint"
+require_relative "lib/session_ledger"
+
+# Intent 331a (D6/R8): every caller-added screen kind file registers itself
+# on load (ScreenPaint.register), so this glob is the ONLY wiring a new kind
+# needs - no edit here, no edit to screen_paint.rb. Sorted for a
+# deterministic load order; tolerates the directory being absent or empty
+# (Dir.glob answers [] either way), which is this repo's own state today.
+Dir.glob(File.join(__dir__, "lib", "screens", "*.rb")).sort.each { |f| require_relative f }
 
 def usage_abort(message)
   warn "report-screen: #{message}"
   exit 2
 end
 
-# The one place allowed to shell out (D2/D20): resolves the nearest git tag
-# reachable from the repo this script lives in, so `render_delivered`'s
-# version field and the `ship` evidence row are never invented. The pure
-# module never reads git itself; this is injected as `tag_reader:`.
-def git_tag_reader(repo_root)
-  lambda do |_intent_dir|
-    return nil unless File.exist?(File.join(repo_root, ".git"))
-    tag = `git -C #{repo_root} describe --tags --abbrev=0 2>/dev/null`.strip
-    tag.empty? ? nil : tag
+# The one place allowed to shell out (D2/D20): resolves the tag that CONTAINS
+# the intent's merge commit, in the project's own repository, so the version
+# on the delivered screen is the release that merge shipped in. The
+# repository comes from --repo, else from projects.yml beside the store (the
+# installed layout, <home>/projects/<slug>/store/<id>), else the repository
+# this script lives in (the in-repo layout, `include_self: true`) - unless
+# `include_self: false` (the branch reader, D23), in which case a global
+# intent's repo never falls back to the script's own repository, since that
+# is not the intent's repository at all. No merge sha, no repository, or no
+# containing tag all answer nil, and the screen says "not recorded" rather
+# than guessing from HEAD (D14). The pure module never reads git.
+def resolve_repo(intent_dir, explicit_repo, script_dir, include_self: true)
+  candidates = []
+  candidates << File.expand_path(explicit_repo) if explicit_repo
+  if (m = intent_dir.match(%r{\A(.*)/(?:projects|stores)/([^/]+)/store/[^/]+\z}))
+    home, slug = m[1], m[2]
+    projects_yml = File.join(home, "projects.yml")
+    if File.exist?(projects_yml)
+      data = begin
+        YAML.safe_load(File.read(projects_yml))
+      rescue StandardError
+        nil
+      end
+      entry = data.is_a?(Hash) && data["projects"].is_a?(Hash) ? data["projects"][slug] : nil
+      path = entry.is_a?(Hash) ? entry["path"].to_s : ""
+      candidates << File.expand_path(path) unless path.empty?
+    end
+  end
+  candidates << File.expand_path("..", script_dir) if include_self
+  candidates.find { |c| File.exist?(File.join(c, ".git")) }
+end
+
+def git_tag_reader(explicit_repo:, script_dir:)
+  lambda do |intent_dir|
+    sha = ReportScreen.merge_sha(intent_dir)
+    return nil unless sha
+    repo = resolve_repo(intent_dir, explicit_repo, script_dir)
+    return nil unless repo
+    tags = `git -C #{repo.shellescape} tag --contains #{sha.shellescape} 2>/dev/null`
+    versions = tags.lines.map(&:strip).reject(&:empty?).filter_map do |tag|
+      v = tag.sub(/\Av/, "")
+      Gem::Version.correct?(v) ? [Gem::Version.new(v), tag] : nil
+    end
+    versions.min_by(&:first)&.last
+  end
+end
+
+# D9/D23: the injected branch reader. flow_base (a pure YAML read, never
+# git) wins when the intent's project names a flow base; otherwise the
+# repository's remote HEAD, else whichever of main/master exists. Resolves
+# the repo with `include_self: false` (D23): a global-store intent must
+# never fall back to the script's OWN repository (~/.plastic itself, on
+# "main" in the installed layout) and print a confident, wrong branch.
+def git_branch_reader(explicit_repo:, script_dir:)
+  lambda do |intent_dir|
+    flow = ReportScreen.flow_base(intent_dir)
+    next flow if flow && !flow.to_s.empty?
+
+    repo = resolve_repo(intent_dir, explicit_repo, script_dir, include_self: false)
+    next nil unless repo
+
+    branch = `git -C #{repo.shellescape} symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null`.strip
+    branch = branch.sub(%r{\Aorigin/}, "")
+    next branch unless branch.empty?
+
+    %w[main master].find do |b|
+      system("git", "-C", repo, "rev-parse", "--verify", "--quiet", b, out: File::NULL, err: File::NULL)
+    end
   end
 end
 
@@ -49,6 +125,11 @@ verb = args.shift
 changed = nil
 ansi = false
 template_path = nil
+repo_flag = nil
+session_flag = nil
+since_flag = nil
+ledger_root_flag = nil
+store_root_flag = nil
 positional = []
 
 while (arg = args.shift)
@@ -60,15 +141,25 @@ while (arg = args.shift)
     ansi = true
   when "--all"
     positional << "--all"
+  when "--repo"
+    repo_flag = args.shift or usage_abort("--repo needs a path")
   when "--template"
     template_path = args.shift or usage_abort("--template needs a path")
+  when "--session"
+    session_flag = args.shift or usage_abort("--session needs a value")
+  when "--since"
+    since_flag = args.shift or usage_abort("--since needs a value")
+  when "--ledger-root"
+    ledger_root_flag = args.shift or usage_abort("--ledger-root needs a path")
+  when "--store-root"
+    store_root_flag = args.shift or usage_abort("--store-root needs a path")
   else
     usage_abort("unknown flag #{arg.inspect}") if arg.start_with?("--") && arg != "--all"
     positional << arg
   end
 end
 
-usage_abort("usage: report-screen state|delivered|delay <intent_dir> [--changed \"<text>\"] [--ansi]") unless verb
+usage_abort("usage: report-screen plan|state|delivered|delay|session <intent_dir> [--changed \"<text>\"] [--ansi]") unless verb
 
 all_mode = positional.delete("--all") ? true : false
 target = positional.first
@@ -82,6 +173,16 @@ def paint(text, ansi_enabled, _renderer_path = nil)
 end
 
 case verb
+when "plan"
+  usage_abort("usage: report-screen plan <intent_dir> [--ansi]") unless target
+  intent_dir = File.expand_path(target)
+  usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
+  store_root = File.expand_path("../..", intent_dir)
+  template_path ||= File.expand_path("../templates/report-plan.md", __dir__)
+  usage_abort("template not found at #{template_path}") unless File.exist?(template_path)
+  out = ReportScreen.render_plan(intent_dir: intent_dir, store_root: store_root,
+                                  template: File.read(template_path))
+  $stdout.write paint(out, ansi_enabled)
 when "state"
   if all_mode
     usage_abort("usage: report-screen state --all <store_root>") unless target
@@ -104,8 +205,9 @@ when "delivered"
   usage_abort("usage: report-screen delivered <intent_dir>") unless target
   intent_dir = File.expand_path(target)
   usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
-  repo_root = File.expand_path("..", __dir__)
-  out = ReportScreen.render_delivered(intent_dir: intent_dir, tag_reader: git_tag_reader(repo_root))
+  out = ReportScreen.render_delivered(intent_dir: intent_dir,
+                                      tag_reader: git_tag_reader(explicit_repo: repo_flag, script_dir: __dir__),
+                                      branch_reader: git_branch_reader(explicit_repo: repo_flag, script_dir: __dir__))
   $stdout.write paint(out, ansi_enabled)
 when "delay"
   usage_abort("usage: report-screen delay <intent_dir>") unless target
@@ -113,8 +215,67 @@ when "delay"
   usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
   out = ReportScreen.render_delay(intent_dir: intent_dir)
   $stdout.write paint(out, ansi_enabled)
+when "session"
+  usage_abort("usage: report-screen session <tier_root> [--session <id>] [--since <iso>] [--ledger-root <dir>] [--ansi]") unless target
+  store_root = File.expand_path(target)
+  usage_abort("#{store_root} is not a store (no INDEX.md)") unless File.exist?(File.join(store_root, "INDEX.md"))
+
+  now = Time.now
+  session_id = session_flag || ENV[SessionLedger::SESSION_ID_ENV_KEY]
+  ledger_root = ledger_root_flag ? File.expand_path(ledger_root_flag) : ReportScreen.default_ledger_root(store_root)
+
+  if since_flag
+    begin
+      Time.parse(since_flag)
+    rescue ArgumentError
+      usage_abort("--since needs an ISO timestamp, got #{since_flag.inspect}")
+    end
+  end
+
+  dirs, skipped = ReportScreen.session_delivered_dirs(ledger_root: ledger_root, tier_root: store_root,
+                                                       session: session_id, since: since_flag, now: now)
+  # D17: the widened window is announced whether the id was missing or simply
+  # matched nothing. A resumed background job carries a session id that is not
+  # the one on the ledger lines, and that case must not answer silently. An
+  # explicit --since is the caller naming the window, so it needs no note.
+  note =
+    if since_flag
+      nil
+    elsif session_id.nil? || session_id.to_s.strip.empty?
+      ReportScreen.window_note(ReportScreen.fallback_day(ledger_root, SessionLedger.day_id(now)),
+                               "no session id given")
+    elsif !ReportScreen.session_tagged?(ledger_root: ledger_root, session: session_id, now: now)
+      ReportScreen.window_note(ReportScreen.fallback_day(ledger_root, SessionLedger.day_id(now)),
+                               "this session has no line in the day ledger")
+    end
+
+  out = ReportScreen.render_session(
+    dirs: dirs, skipped: skipped, store_root: store_root,
+    tag_reader: git_tag_reader(explicit_repo: nil, script_dir: __dir__),
+    branch_reader: git_branch_reader(explicit_repo: nil, script_dir: __dir__),
+    note: note, now: now, painter: ->(text) { paint(text, ansi_enabled) }
+  )
+  $stdout.write out
+when "roadmap"
+  usage_abort("usage: report-screen roadmap <roadmap.md> plan|state|delivered [--ansi] [--store-root <dir>]") if positional.empty?
+  roadmap_path = File.expand_path(positional[0])
+  usage_abort("#{roadmap_path} does not exist") unless File.exist?(roadmap_path)
+  sub_verb = positional[1]
+  usage_abort("usage: report-screen roadmap <roadmap.md> plan|state|delivered") unless sub_verb
+  unless %w[plan state delivered].include?(sub_verb)
+    usage_abort("unknown sub-verb #{sub_verb.inspect} (use plan|state|delivered)")
+  end
+  roadmap_store_root = store_root_flag ? File.expand_path(store_root_flag) : nil
+  out = ReportScreen.render_roadmap(path: roadmap_path, verb: sub_verb, store_root: roadmap_store_root)
+  $stdout.write paint(out, ansi_enabled)
+when "archive"
+  usage_abort("usage: report-screen archive <store_root>") unless target
+  store_root = File.expand_path(target)
+  usage_abort("#{store_root} is not a store (no INDEX.md)") unless File.exist?(File.join(store_root, "INDEX.md"))
+  out = ReportScreen.render_archive(store_root)
+  $stdout.write paint(out, ansi_enabled)
 else
-  usage_abort("unknown verb #{verb.inspect} (use state|delivered|delay)")
+  usage_abort("unknown verb #{verb.inspect} (use plan|state|delivered|delay|session|roadmap|archive)")
 end
 
 exit 0

package/scripts/roadmap-graph

@@ -0,0 +1,119 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# roadmap-graph - the CLI over the roadmap graph model (intent 337, G4):
+# `check`, `render`, `migrate`, every verb honouring --dry-run.
+#
+# Usage:
+#   roadmap-graph check <roadmap.md> [--dry-run]
+#   roadmap-graph render <roadmap.md> [--dry-run]
+#   roadmap-graph migrate <roadmap.md> [--dry-run]
+#
+# Exit codes:
+#   0 - printed / rendered / migrated cleanly (or a migrate skip: the
+#       roadmap already carries a graph)
+#   1 - a real finding: a cyclic graph, a dangling id, or a render/migrate
+#       refusal (no ## Graph, no grouping heading)
+#   2 - usage: no argument, an unknown verb, or a missing/non-file path
+
+require_relative "lib/roadmap_graph"
+require_relative "lib/roadmap_render"
+require_relative "lib/roadmap_migration"
+
+module RoadmapGraphCli
+  module_function
+
+  VERBS = %w[check render migrate].freeze
+
+  def usage
+    warn "Usage: roadmap-graph <#{VERBS.join('|')}> <roadmap.md> [--dry-run]"
+  end
+
+  def main(argv)
+    args = argv.dup
+    dry_run = !!args.delete("--dry-run")
+
+    verb = args.shift
+    unless verb && VERBS.include?(verb)
+      warn "roadmap-graph: unknown verb #{verb.inspect} (use #{VERBS.join(', ')})" if verb
+      usage
+      return 2
+    end
+
+    path = args.shift
+    unless path && File.file?(path)
+      warn "roadmap-graph: #{path.inspect} is not a file"
+      return 2
+    end
+
+    case verb
+    when "check" then check(path)
+    when "render" then render(path, dry_run)
+    when "migrate" then migrate(path, dry_run)
+    end
+  end
+
+  def check(path)
+    result = RoadmapGraph.analyze(path)
+    unless result[:has_graph]
+      warn "roadmap-graph check: #{result[:reason]}"
+      return 1
+    end
+    if result[:cycle]
+      warn "roadmap-graph check: cyclic graph: #{result[:cycle].join(' > ')}"
+      return 1
+    end
+    if result[:reason]
+      warn "roadmap-graph check: #{result[:reason]}"
+      return 1
+    end
+
+    puts "Batches: #{result[:batches].map { |b| b.join(', ') }.join(' | ')}"
+    puts "Ready: #{result[:ready].join(', ')}"
+    puts "Dead ends: #{result[:dead_ends].join(', ')}" unless result[:dead_ends].empty?
+
+    unless result[:dangling].empty?
+      warn "roadmap-graph check: graph names #{result[:dangling].map(&:inspect).join(', ')}, no batch entry"
+      return 1
+    end
+
+    0
+  end
+
+  def render(path, dry_run)
+    result = RoadmapRender.write(path, dry_run: dry_run)
+    unless result[:ok]
+      warn "roadmap-graph render: #{result[:error]}"
+      return 1
+    end
+
+    if dry_run
+      puts result[:content]
+    else
+      puts "roadmap-graph render: wrote #{path}"
+    end
+    0
+  end
+
+  def migrate(path, dry_run)
+    result = RoadmapMigration.write(path, dry_run: dry_run)
+    unless result[:ok]
+      if result[:skipped]
+        puts "roadmap-graph migrate: #{result[:reason]}"
+        return 0
+      end
+      warn "roadmap-graph migrate: #{result[:reason]}"
+      return 1
+    end
+
+    if dry_run
+      puts result[:content]
+    else
+      puts "roadmap-graph migrate: wrote #{path}"
+    end
+    0
+  end
+end
+
+exit(RoadmapGraphCli.main(ARGV)) if $PROGRAM_NAME == __FILE__

package/scripts/roadmap-savepoint

@@ -18,6 +18,7 @@
 # rebuilds an empty ledger.
 
 require_relative "lib/roadmap_savepoint"
+require_relative "lib/guarded_append"
 
 def opt(args, name)
   (i = args.index(name)) && args[i + 1]
@@ -47,6 +48,12 @@ when "append"
   rescue ArgumentError => e
     warn "append: #{e.message}"
     exit 2
+  rescue GuardedAppend::Unavailable => e
+    # Intent 335 (spec D14): the write guard could not be taken; nothing was written. Exit 4
+    # rather than let a backtrace reach the six skill recipes that drive this CLI - it rescues
+    # ArgumentError alone today and would otherwise print one straight to the terminal.
+    warn "append: #{e.message}"
+    exit 4
   end
 
 when "rebuild"