@zalom/plastic 1.1.0 → 1.1.2

package/scripts/lib/roadmap_savepoint.rb

@@ -0,0 +1,213 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "time"
+require "fileutils"
+
+# RoadmapSavepoint - the roadmap's machine counterpart to its human `## Log` (intent 134).
+#
+# Mirrors scripts/lib/qmd_sync.rb's class shape and the cycle-step savepoint ledger in
+# scripts/lib/bridge.rb (append semantics: idempotent `(event, detail)` pair dedup, one
+# deterministic append primitive). Constructor-DI, hermetic: no eval, no ENV or global config
+# seam, clock injected through `now:`. Two operations:
+#
+#   append(roadmap_path, event, detail, now:)  - one deterministic, idempotent append
+#   rebuild(roadmap_path)                       - reconstruct the ledger from the roadmap's
+#                                                  `## Log` (and, for delivered wave entries with
+#                                                  no matching Log line, from INDEX `## Completed`)
+#
+# The ledger is sugar on top of the roadmap file: derived, rebuildable, never a status source.
+# INDEX.md stays the single status writer.
+module RoadmapSavepoint
+  module_function
+
+  EVENTS = %w[created dispatched parked merged release handoff closed added reordered wave].freeze
+
+  # Keyword -> event classification for `rebuild`, checked top to bottom, first match wins.
+  # Kept small and deterministic (action 1). Order matters: more specific/rarer words are
+  # checked before the broader "wave" fallback so an incidental "wave" mention in an otherwise
+  # classifiable line never shadows its real event.
+  KEYWORD_TABLE = [
+    [/\bclosed\b/i, "closed"],
+    [/\bhanded off\b|\bhandoff\b/i, "handoff"],
+    [/\breleased?\b|\bcut\b|\btagged\b/i, "release"],
+    [/\bparked\b|\bblocked\b|\bholds?\b/i, "parked"],
+    [/\bdelivered\b|\bmerged\b|\bshipped\b/i, "merged"],
+    [/\bdelivering\b|\bdispatch(?:ed)?\b/i, "dispatched"],
+    [/\breordered\b/i, "reordered"],
+    [/\badded\b|\badds\b/i, "added"],
+    [/\bcreated\b/i, "created"],
+    [/\bwave\b/i, "wave"],
+  ].freeze
+
+  # --- append -----------------------------------------------------------------
+
+  # The name-paired sibling ledger for a roadmap path: roadmaps/<slug>.md becomes
+  # roadmaps/<slug>.savepoint.md. Resolves correctly for a live roadmap and for one already
+  # moved under roadmaps/archived/, because both are plain path substitutions.
+  def ledger_path_for(roadmap_path)
+    roadmap_path.sub(/\.md\z/, ".savepoint.md")
+  end
+
+  # `(event, detail)` pairs already recorded in a ledger file, the dedup key (D2): two
+  # `dispatched` events with different details are distinct, so the event word alone would be
+  # too coarse a key.
+  def recorded_pairs(ledger_path)
+    return [] unless File.exist?(ledger_path)
+    File.read(ledger_path).each_line.filter_map { |line| parse_pair(line) }
+  end
+
+  def parse_pair(line)
+    parts = line.strip.split(/\s{2,}/)
+    parts.length >= 3 ? [parts[1], parts[2]] : nil
+  end
+  private_class_method :parse_pair
+
+  # Append one ledger line "<iso8601>  <event>  <detail>" unless `(event, detail)` is already
+  # 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)
+    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
+  end
+
+  def format_line(time, event, detail)
+    "#{time.utc.iso8601}  #{event}  #{detail.to_s.strip}\n"
+  end
+  private_class_method :format_line
+
+  # --- rebuild ------------------------------------------------------------------
+
+  # Reconstruct the paired ledger deterministically from the roadmap file's `## Log` (never the
+  # roadmap `.md`, which is read-only here), cross-checked against `## Waves` and the tier's
+  # INDEX so every `delivered` wave entry has a `merged` line. Every timestamp comes from an
+  # on-disk source (the Log, or INDEX `## Completed`); an entry with no recoverable timestamp is
+  # not emitted (D4, never invented). Overwrites the ledger (the one operation allowed to rewrite
+  # it, matching `Bridge.rebuild_savepoint`). Returns the number of lines written.
+  def rebuild(roadmap_path)
+    text = File.read(roadmap_path)
+    log_lines = classify_log(section_body(text, "Log"))
+    delivered_ids = delivered_wave_ids(section_body(text, "Waves"))
+    backfilled = backfill_merged_lines(log_lines, delivered_ids, roadmap_path)
+
+    lines = dedup_pairs(log_lines + backfilled)
+    File.write(ledger_path_for(roadmap_path), lines.map { |t, e, d| format_line(t, e, d) }.join)
+    lines.length
+  end
+
+  # Every `- YYYY-MM-DD HH:MM UTC ...` line in the `## Log` body, classified into
+  # [time, event, detail]. A line with no keyword match is dropped (no event to record); a
+  # continuation line (no date prefix) never matches the header pattern, so it is inherently
+  # ignored for classification, per action 1.
+  def classify_log(log_body)
+    log_body.each_line.filter_map { |line| classify_log_line(line) }
+  end
+  private_class_method :classify_log
+
+  LOG_LINE = /\A-\s+(\d{4}-\d{2}-\d{2})\s+(\d{2}:\d{2})\s+UTC\s+(.*)\z/.freeze
+
+  def classify_log_line(line)
+    m = line.strip.match(LOG_LINE)
+    return nil unless m
+    event = classify_event(m[3])
+    return nil unless event
+    [parse_log_time(m[1], m[2]), event, m[3].strip]
+  end
+  private_class_method :classify_log_line
+
+  def parse_log_time(date, hhmm)
+    y, mo, d = date.split("-").map(&:to_i)
+    h, mi = hhmm.split(":").map(&:to_i)
+    Time.utc(y, mo, d, h, mi, 0)
+  end
+  private_class_method :parse_log_time
+
+  def classify_event(text)
+    hit = KEYWORD_TABLE.find { |regex, _event| text =~ regex }
+    hit && hit[1]
+  end
+  private_class_method :classify_event
+
+  WAVE_ENTRY = /\A-\s*\[([ xX])\]\s+(\S+)\s+.+—\s*(\S+)\s*\z/.freeze
+
+  # Intent ids of every `[x] ... — delivered` entry in the `## Waves` body.
+  def delivered_wave_ids(waves_body)
+    waves_body.each_line.filter_map do |line|
+      m = line.strip.match(WAVE_ENTRY)
+      next nil unless m
+      checked = m[1].strip.downcase == "x"
+      status = m[3].strip.downcase
+      m[2] if checked && status == "delivered"
+    end
+  end
+  private_class_method :delivered_wave_ids
+
+  # For every delivered wave id with no `merged` line already among `log_lines` (the "matching
+  # Log line" source, D4), fall back to the tier's INDEX `## Completed` section (the second
+  # on-disk source D4 allows). No source at all -> the id is silently skipped, never invented.
+  # Backfilled lines are appended after the Log-derived pass (a reconciliation pass run after
+  # reconstruction), each carrying its own real on-disk-sourced timestamp even when that
+  # timestamp sorts earlier than same-day Log lines above it (INDEX only carries a date, so the
+  # time floors to midnight UTC rather than inventing a time-of-day).
+  def backfill_merged_lines(log_lines, delivered_ids, roadmap_path)
+    index_path = index_path_for(roadmap_path)
+    delivered_ids.filter_map do |id|
+      next nil if log_lines.any? { |_t, event, detail| event == "merged" && detail =~ /\b#{Regexp.escape(id)}\b/ }
+      date = index_completed_date(index_path, id)
+      next nil unless date
+      [Time.utc(*date.split("-").map(&:to_i)), "merged", "#{id} (from INDEX Completed)"]
+    end
+  end
+  private_class_method :backfill_merged_lines
+
+  # The tier root is the parent of `roadmaps/` (a live roadmap's grandparent, or, for one
+  # already moved to `roadmaps/archived/`, its great-grandparent); INDEX.md is that root's
+  # sibling file, matching the layout `plastic-roadmap`'s file-format doc defines.
+  def index_path_for(roadmap_path)
+    dir = File.dirname(roadmap_path)
+    dir = File.dirname(dir) if File.basename(dir) == "archived"
+    File.join(File.dirname(dir), "INDEX.md")
+  end
+  private_class_method :index_path_for
+
+  def index_completed_date(index_path, id)
+    return nil unless index_path && File.exist?(index_path)
+    section_body(File.read(index_path), "Completed").each_line do |line|
+      next unless line.strip.start_with?("- [#{id} ")
+      m = line.match(/\)\s*—\s*(\d{4}-\d{2}-\d{2})\b/)
+      return m[1] if m
+    end
+    nil
+  end
+  private_class_method :index_completed_date
+
+  # The body text of a `## <heading>` section: everything after the heading line up to (but not
+  # including) the next `## ` heading or end of file.
+  def section_body(text, heading)
+    m = text.match(/^##\s+#{Regexp.escape(heading)}\s*$(.*?)(?=^##\s|\z)/m)
+    m ? m[1] : ""
+  end
+  private_class_method :section_body
+
+  # Stable dedup on the `(event, detail)` pair, keeping the first occurrence in the given
+  # (already chronological-then-backfill-appended) order.
+  def dedup_pairs(lines)
+    seen = []
+    lines.select do |_t, event, detail|
+      pair = [event, detail]
+      next false if seen.include?(pair)
+      seen << pair
+      true
+    end
+  end
+  private_class_method :dedup_pairs
+end

package/scripts/lib/skill_lint.rb

@@ -0,0 +1,304 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+
+# SkillLint: deterministic, dependency-injected engine that runs five
+# structural checks over a directory of Agent Skills (intent 85b).
+#
+# Pure and DI: constructed with an injected `skills_dir`, performs no writes,
+# no `eval`, and reads no ambient config beyond the injected directory. Mirrors
+# the CLI-over-lib shape of `scripts/lib/intent_validator.rb`: the `skill-lint`
+# CLI (ACTION_2) is a thin wrapper, `scripts/doctor.rb` (ACTION_4) consumes the
+# same engine for an advisory finding, and `test/skill_lint_test.rb` (ACTION_3)
+# proves every check red-and-green plus a no-skip-list live-tree guard.
+#
+# Each violation is a Hash:
+#   { check:, skill:, file:, line:, rule:, message: }
+# `check` is one of the five check-ids below, `skill` is the skill directory
+# basename, `file` is the offending path, `line` is an Integer where locatable
+# else nil, `rule` cites the standard being enforced, `message` is an
+# actionable fix instruction.
+class SkillLint
+  # A binding keyword: a mention's paragraph carries an observable trigger
+  # condition when it names one of these (word-boundary, case-insensitive).
+  BINDING_KEYWORD_RE = /\b(when|if|before|after|while)\b/i
+
+  # A `to <verb>` or `for <noun-phrase>` purpose clause.
+  PURPOSE_RE = /\b(to|for)\s+\S/i
+
+  Result = Struct.new(:violations) do
+    def ok?
+      violations.empty?
+    end
+
+    # Slice violations down to one check-id, e.g. for a doctor finding or a
+    # red-proof assertion.
+    def violations_for(check_id)
+      violations.select { |v| v[:check] == check_id }
+    end
+  end
+
+  def initialize(skills_dir:)
+    @skills_dir = skills_dir
+  end
+
+  def run
+    violations = []
+
+    skill_md_paths.each do |skill_md|
+      skill_dir = File.dirname(skill_md)
+      content = File.read(skill_md)
+
+      violations.concat(check_body_budget(skill_dir, skill_md, content))
+      violations.concat(check_frontmatter_validity(skill_dir, skill_md, content))
+      violations.concat(check_bare_pointer(skill_dir, skill_md, content))
+      violations.concat(check_orphan_files(skill_dir))
+      violations.concat(check_references_depth(skill_dir))
+    end
+
+    Result.new(violations)
+  end
+
+  private
+
+  def skill_md_paths
+    Dir.glob(File.join(@skills_dir, "*", "SKILL.md")).sort
+  end
+
+  def skill_name(skill_dir)
+    File.basename(skill_dir)
+  end
+
+  def violation(check:, skill:, file:, line:, rule:, message:)
+    { check: check, skill: skill, file: file, line: line, rule: rule, message: message }
+  end
+
+  # Frontmatter split uses the shared convention (scripts/lib/intent_validator.rb):
+  # `content.split("---", 3)`; parts[1] is the frontmatter text, parts[2] is the
+  # body. Also computes the body's starting line number (0-based line count of
+  # everything before the body) so callers can report absolute file line
+  # numbers, not just body-relative ones.
+  def frontmatter_and_body(content)
+    parts = content.split("---", 3)
+    return { frontmatter: nil, body: content, body_offset_lines: 0 } if parts.length < 3
+
+    prefix_len = parts[0].length + 3 + parts[1].length + 3
+    prefix = content[0...prefix_len]
+    { frontmatter: parts[1], body: parts[2], body_offset_lines: prefix.count("\n") }
+  end
+
+  # --- 1. body-budget ---
+
+  def check_body_budget(skill_dir, skill_md, content)
+    violations = []
+    body = frontmatter_and_body(content)[:body]
+    name = skill_name(skill_dir)
+
+    line_count = body.lines.count
+    if line_count >= 500
+      violations << violation(
+        check: "body-budget", skill: name, file: skill_md, line: nil,
+        rule: "body under 500 lines",
+        message: "SKILL.md body is #{line_count} lines; move detail into references/*.md to get under 500"
+      )
+    end
+
+    tokens = (body.split(/\s+/).reject(&:empty?).length * 1.3).round
+    if tokens >= 5000
+      violations << violation(
+        check: "body-budget", skill: name, file: skill_md, line: nil,
+        rule: "body under about 5000 tokens (word-based estimate)",
+        message: "SKILL.md body is about #{tokens} tokens (word-based estimate); move detail into references/*.md to get under 5000"
+      )
+    end
+
+    violations
+  end
+
+  # --- 2. frontmatter-validity ---
+
+  def check_frontmatter_validity(skill_dir, skill_md, content)
+    violations = []
+    name = skill_name(skill_dir)
+    frontmatter_text = frontmatter_and_body(content)[:frontmatter]
+
+    begin
+      fm = YAML.safe_load(frontmatter_text.to_s)
+    rescue Psych::SyntaxError
+      violations << violation(
+        check: "frontmatter-validity", skill: name, file: skill_md, line: nil,
+        rule: "frontmatter must survive strict YAML.safe_load",
+        message: "SKILL.md frontmatter fails YAML.safe_load; quote scalar values that contain an unquoted \": \" sequence"
+      )
+      return violations
+    end
+    fm = {} unless fm.is_a?(Hash)
+
+    expected_name = "plastic-#{name}"
+    if fm["name"] != expected_name
+      violations << violation(
+        check: "frontmatter-validity", skill: name, file: skill_md, line: nil,
+        rule: "name: must equal plastic-<directory>",
+        message: "frontmatter name: is #{fm["name"].inspect}; expected #{expected_name.inspect}"
+      )
+    end
+
+    user_invocable = fm["user-invocable"]
+    unless user_invocable == true || user_invocable == false
+      violations << violation(
+        check: "frontmatter-validity", skill: name, file: skill_md, line: nil,
+        rule: "user-invocable: must be present and boolean",
+        message: "frontmatter user-invocable: is #{user_invocable.inspect}; must be present and true or false"
+      )
+    end
+
+    violations
+  end
+
+  # --- 3. bare-pointer ---
+
+  def check_bare_pointer(skill_dir, skill_md, content)
+    violations = []
+    ref_files = Dir.glob(File.join(skill_dir, "references", "*.md")).sort
+    return violations if ref_files.empty?
+
+    parsed = frontmatter_and_body(content)
+    body_lines = parsed[:body].lines
+    offset = parsed[:body_offset_lines]
+    blocks = paragraph_blocks(body_lines)
+    name = skill_name(skill_dir)
+
+    ref_files.each do |ref_file|
+      base = File.basename(ref_file)
+      mention_indices = (0...body_lines.length).select { |i| body_lines[i].include?(base) }
+      next if mention_indices.empty? # zero mentions is an orphan (check 4), not a bare pointer
+
+      bound = mention_indices.any? { |i| bound_mention?(body_lines[i], i, blocks, base) }
+      next if bound
+
+      first = mention_indices.first
+      violations << violation(
+        check: "bare-pointer", skill: name, file: skill_md, line: offset + first + 1,
+        rule: "every reference link must bind to an observable trigger condition, never a bare pointer",
+        message: "#{base} is only ever a bare pointer; add a when/if/before/after/while clause or a " \
+                  "to/for purpose so the trigger is observable"
+      )
+    end
+
+    violations
+  end
+
+  def bound_mention?(line, index, blocks, base)
+    stripped = line.strip
+    return table_row_bound?(stripped, base) if stripped.start_with?("|")
+
+    block = blocks.find { |b| index.between?(b[:start], b[:end]) }
+    block_text = block ? block[:text] : line
+
+    # Narrow to the unit(s) that actually mention the reference, so an
+    # unrelated unit elsewhere in the same paragraph cannot launder a
+    # genuinely bare pointer through an incidental "to"/"for" (an ordinary
+    # preposition, not a binding purpose clause). Split on BOTH sentence
+    # boundaries (.!?) AND list-item starts, so a bullet list (which has no
+    # terminal punctuation between items) does not collapse into one unit
+    # whose bound siblings launder a bare bullet -- the trailing "References"
+    # list pattern (most bullets bound, one forgotten) this linter exists to
+    # catch. Keep only units that mention `base`. Falls back to the whole
+    # block when no unit boundary contains the mention (e.g. a mid-sentence
+    # line wrap with no terminal punctuation nearby), so the legitimate
+    # multi-line-wrapped case still binds.
+    #
+    # Known conservative limitation (documented, not closed): a bare mention
+    # with NO unit boundary of its own (no leading list marker, no preceding
+    # terminal punctuation) immediately followed by an unrelated sentence
+    # carrying "to"/"for" can still borrow that neighbor's binding via the
+    # empty-fallback path. Closing this structurally risks re-breaking the
+    # legitimate wrapped-sentence case (which also relies on the fallback),
+    # so it stays open; see intent 85b insights.
+    units = block_text.split(/(?<=[.!?])\s+|\n(?=\s*(?:[-*+]|\d+[.)])\s)/)
+    mentioning = units.select { |s| s.include?(base) }
+    scoped_text = mentioning.empty? ? block_text : mentioning.join(" ")
+
+    scoped_text.match?(BINDING_KEYWORD_RE) || scoped_text.match?(PURPOSE_RE)
+  end
+
+  # A table row is bound when some OTHER cell (not the one carrying the
+  # reference path) has visible text (the trigger-condition column).
+  def table_row_bound?(stripped_line, base)
+    cells = stripped_line.split("|").map(&:strip).reject(&:empty?)
+    other_cells = cells.reject { |c| c.include?(base) }
+    !other_cells.empty?
+  end
+
+  # Group body lines into blank-line-delimited paragraph blocks so a mention
+  # that trails a wrapped sentence (the binding keyword on the line above) is
+  # still evaluated against its full paragraph, not just its own physical line.
+  def paragraph_blocks(lines)
+    blocks = []
+    start = nil
+    lines.each_with_index do |line, i|
+      if line.strip.empty?
+        blocks << { start: start, end: i - 1, text: lines[start..(i - 1)].join } if start
+        start = nil
+      else
+        start ||= i
+      end
+    end
+    blocks << { start: start, end: lines.length - 1, text: lines[start..-1].join } if start
+    blocks
+  end
+
+  # --- 4. orphan-files ---
+
+  def check_orphan_files(skill_dir)
+    violations = []
+    ref_files = Dir.glob(File.join(skill_dir, "references", "*.md")).sort
+    return violations if ref_files.empty?
+
+    other_files = Dir.glob(File.join(skill_dir, "**", "*")).select { |p| File.file?(p) }
+    name = skill_name(skill_dir)
+
+    ref_files.each do |ref_file|
+      base = File.basename(ref_file)
+      mentioned = other_files.any? do |other|
+        next false if other == ref_file
+
+        File.read(other).include?(base)
+      end
+      next if mentioned
+
+      violations << violation(
+        check: "orphan-files", skill: name, file: ref_file, line: nil,
+        rule: "every references/ file must be routed from the skill",
+        message: "#{base} is never mentioned anywhere in the skill directory; route it from SKILL.md or delete it"
+      )
+    end
+
+    violations
+  end
+
+  # --- 5. references-depth ---
+
+  def check_references_depth(skill_dir)
+    violations = []
+    refs_root = File.join(skill_dir, "references")
+    return violations unless File.directory?(refs_root)
+
+    name = skill_name(skill_dir)
+    Dir.glob(File.join(refs_root, "**", "*")).each do |path|
+      next unless File.file?(path)
+
+      rel = path.sub("#{refs_root}/", "")
+      next unless rel.include?("/")
+
+      violations << violation(
+        check: "references-depth", skill: name, file: path, line: nil,
+        rule: "references stay one level deep",
+        message: "#{rel} is nested under references/; move it to a flat references/*.md file"
+      )
+    end
+
+    violations
+  end
+end

package/scripts/lib/worktree.rb

@@ -79,6 +79,21 @@ module Worktree
     }
   end
 
+  # Derive the OS-HOME level (the PARENT of `.plastic`) from an intent store
+  # path, anchored on the `.plastic` path segment (Defect 1, intent 169): a
+  # store is always `<plastic_home>/store` or
+  # `<plastic_home>/projects/<slug>/store`, and `<plastic_home>` is always the
+  # `.plastic` dir. Returns nil when `store` is blank or carries no `.plastic`
+  # segment, so callers fall back to their own `home:` default rather than
+  # resolving anything. Pure: no `ENV[...]` read, no I/O.
+  def home_from_store(store)
+    return nil if blank?(store)
+    parts = File.expand_path(store.to_s).split(File::SEPARATOR)
+    idx = parts.rindex(".plastic")
+    return nil unless idx
+    parts[0...idx].join(File::SEPARATOR)
+  end
+
   # Absolute repo path for a project slug from `~/.plastic/projects.yml`, or nil.
   # Reuses the qmd_sync safe-loader pattern: any failure yields nil.
   def repo_for(slug, home: Dir.home)
@@ -106,6 +121,12 @@ module Worktree
     store = intent["store"].to_s
     intent_slug = slug_from_dir(intent["dir"]) || slug_from_dir(store)
 
+    # Defect 1 fix (intent 169): derive plastic_home from the already-sandboxed
+    # store path when possible, so a sandboxed board never falls to the real
+    # `Dir.home` default. `home:` remains the fallback only when the store is
+    # blank or carries no recognizable `.plastic` segment.
+    home = home_from_store(store) || home
+
     slug = slug_for_store(store, home: home)
     p = paths(slug: slug, intent_id: intent_id, intent_slug: intent_slug, home: home)
 

package/scripts/new-intent

@@ -282,6 +282,7 @@ def main(argv)
 
   # 2. Create dirs.
   FileUtils.mkdir_p(File.join(intent_dir, "actions"))
+  File.write(File.join(intent_dir, "actions", ".gitkeep"), "")
   FileUtils.mkdir_p(File.join(intent_dir, "resources"))
 
   # 3. Render the born-complete intent file from templates/intent.md.

package/scripts/read-config

@@ -5,7 +5,7 @@
 # Returns scalar values as strings, hash/array values as JSON.
 #
 # Environment:
-#   PLASTIC_GLOBAL_ROOT -- override ~/.plastic (for testing)
+#   PLASTIC_HOME -- override ~/.plastic (for testing)
 
 require "yaml"
 require "json"
@@ -88,7 +88,7 @@ end
 
 # Handle --migrate mode
 if ARGV.include?("--migrate")
-  global_root = ENV.fetch("PLASTIC_GLOBAL_ROOT", File.expand_path("~/.plastic"))
+  global_root = ENV.fetch("PLASTIC_HOME", File.expand_path("~/.plastic"))
   config_path = File.join(global_root, "config.yml")
   config = load_yaml(config_path)
 
@@ -116,7 +116,7 @@ if key.nil? || key.empty?
   exit 1
 end
 
-global_root = ENV.fetch("PLASTIC_GLOBAL_ROOT", File.expand_path("~/.plastic"))
+global_root = ENV.fetch("PLASTIC_HOME", File.expand_path("~/.plastic"))
 global_config = load_yaml(File.join(global_root, "config.yml"))
 
 project_config = {}

package/scripts/roadmap-next

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# roadmap-next - thin CLI over RoadmapQueue (intent 148).
+#
+# The auto loop and plastic-roadmap-continuing both call this instead of ranking roadmap
+# liveness in prose. Queue mode (default) is for the auto loop: it breaks a tie
+# deterministically and reports the winner's frontier state. Which mode (--which) is for
+# plastic-roadmap-continuing: it returns tie_candidates so the skill's single ask can resolve
+# a genuine tie.
+#
+# Usage:
+#   roadmap-next --roadmaps-dir <dir> [--index <path>] [--which]
+#
+# Exits 0 on any successful analysis, including state "none" and "exhausted" (valid answers,
+# not errors). Exits non-zero only on a missing required flag.
+
+require_relative "lib/roadmap_queue"
+require "json"
+
+def opt(args, name)
+  (i = args.index(name)) && args[i + 1]
+end
+
+def usage
+  warn "Usage: roadmap-next --roadmaps-dir <dir> [--index <path>] [--which]"
+  warn "       default mode is the auto-loop queue; --which returns tie_candidates for continuing."
+end
+
+which = !!ARGV.delete("--which")
+roadmaps_dir = opt(ARGV, "--roadmaps-dir")
+index = opt(ARGV, "--index")
+
+if roadmaps_dir.nil?
+  warn "roadmap-next: pass --roadmaps-dir <dir>"
+  usage
+  exit 2
+end
+
+reader = RoadmapQueue.new(roadmaps_dir: roadmaps_dir, index_path: index)
+payload = which ? reader.which : reader.queue
+puts JSON.generate(payload)
+exit 0