@zalom/plastic 1.1.0 → 1.1.1

package/scripts/lib/release_guard.rb

@@ -0,0 +1,62 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+
+# Mechanical guard for stable-cut version preconditions (intent 155). Checks
+# that the three repo version files agree on one version string, and, when a
+# stable/latest cut is declared, that the resolved version carries no
+# pre-release suffix. Pure function over injected paths: no ENV reads, no
+# eval, no global-config seam, hermetically testable and safe to call from
+# both the release workflow and the test suite.
+#
+# Deliberately does not check a repo VERSION file: none exists in this repo.
+# VERSION is an install-target artifact written fresh from package.json at
+# install/update time (scripts/lib/installer_core.rb); it cannot drift
+# independently because it is never committed.
+module ReleaseGuard
+  Result = Struct.new(:ok, :version, :mismatches, :prerelease_suffix, keyword_init: true) do
+    def ok?
+      ok
+    end
+  end
+
+  # package_json / plugin_json / marketplace_json: paths to the three repo
+  # version files. stable: true gates a stable/latest cut (rejects any
+  # pre-release suffix); false allows a suffix, only agreement is checked.
+  def self.check(package_json:, plugin_json:, marketplace_json:, stable:)
+    versions = {
+      "package.json" => read_version(package_json) { |data| data["version"] },
+      ".claude-plugin/plugin.json" => read_version(plugin_json) { |data| data["version"] },
+      ".claude-plugin/marketplace.json" => read_version(marketplace_json) { |data| plastic_plugin_version(data) },
+    }
+
+    canonical = versions["package.json"]
+    mismatches = versions.reject { |_file, version| version && version == canonical }.keys
+
+    suffix = canonical&.match(/-(.+)\z/)&.captures&.first
+    prerelease_violation = stable && !suffix.nil?
+
+    Result.new(
+      ok: mismatches.empty? && !prerelease_violation,
+      version: canonical,
+      mismatches: mismatches,
+      prerelease_suffix: suffix
+    )
+  end
+
+  def self.plastic_plugin_version(data)
+    plugins = Array(data["plugins"])
+    plugin = plugins.find { |p| p["name"] == "plastic" } || plugins.first
+    plugin && plugin["version"]
+  end
+  private_class_method :plastic_plugin_version
+
+  def self.read_version(path)
+    data = JSON.parse(File.read(path))
+    yield data
+  rescue Errno::ENOENT, JSON::ParserError
+    nil
+  end
+  private_class_method :read_version
+end

package/scripts/lib/roadmap_queue.rb

@@ -0,0 +1,285 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "time"
+require "json"
+require_relative "roadmap_savepoint"
+
+# 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
+# future scored ranker (RICE/ICE/WSJF/pairwise) implements the same #rank/#name pair and is
+# injected through RoadmapQueue's ranker: keyword, with no change to parsing, frontier
+# detection, gating, INDEX reconciliation, or the JSON contract.
+class FileOrderRanker
+  def rank(entries)
+    entries
+  end
+
+  def name
+    "file-order"
+  end
+end
+
+# RoadmapQueue - the one deterministic reader the auto loop and plastic-roadmap-continuing
+# both call (intent 148). Constructor-DI, hermetic: clock and paths injected, no eval, no ENV
+# or global config seam. It does two things: liveness-ranks a tier's roadmaps/*.md files
+# (porting plastic-roadmap-continuing's read-time algorithm), and, within the winning
+# roadmap, selects the frontier wave plus its dispatchable set (D-b), value-ordered by the
+# injected ranker (default FileOrderRanker, the intent-173 swap seam). Every frontier token is
+# reconciled against INDEX.md first, INDEX wins. Reads through the 134 ledger via the public
+# RoadmapSavepoint.ledger_path_for; never writes anything, never modifies roadmap_savepoint.rb.
+class RoadmapQueue
+  STATUSES = %w[queued delivering delivered abandoned blocked].freeze
+
+  # Entry line parser, anchored on the status vocabulary rather than end of line, so a trailing
+  # parenthetical ("delivering (owner ruling...)") does not defeat the match. Accepts the em
+  # dash or a hyphen as the separator; roadmap .md files are store-internal and use the em dash.
+  ENTRY = /\A-\s*\[([ xX])\]\s+(\S+)\s+.*?[—-]\s*(queued|delivering|delivered|abandoned|blocked)\b/.freeze
+
+  WAVE_HEADING = /\A###\s+(.+?)\s*\z/.freeze
+
+  LOG_LINE = /\A-\s+(\d{4}-\d{2}-\d{2})\s+(\d{2}:\d{2})\s+UTC\b/.freeze
+
+  def initialize(roadmaps_dir:, index_path: nil, now: Time.now, ranker: FileOrderRanker.new)
+    @roadmaps_dir = roadmaps_dir
+    @index_path   = index_path
+    @now          = now
+    @ranker       = ranker
+  end
+
+  # Auto-loop mode: break ties deterministically, report the winner's frontier state.
+  def queue
+    analyze(mode: "queue")
+  end
+
+  # Continuing mode: return tie_candidates instead of breaking a tie.
+  def which
+    analyze(mode: "which")
+  end
+
+  private
+
+  def analyze(mode:)
+    parsed = reconcile(roadmap_paths.map { |path| parse_roadmap(path) })
+    ranked = rank_candidates(parsed)
+
+    return payload(mode: mode, state: "none", roadmap: nil, frontier_wave: nil,
+                    dispatchable: [], in_flight: [], blocked: [], tie: false,
+                    tie_candidates: []) if ranked.empty?
+
+    tied = tied_group(ranked)
+
+    if tied.length > 1 && mode == "which"
+      tie_candidates = tied.map do |c|
+        { "roadmap" => c[:slug], "last_event" => c[:last_event].utc.iso8601,
+          "reason" => "equally live, tied on last event time" }
+      end
+      return payload(mode: mode, state: "tie", roadmap: nil, frontier_wave: nil,
+                      dispatchable: [], in_flight: [], blocked: [], tie: false,
+                      tie_candidates: tie_candidates)
+    end
+
+    winner = ranked.first
+    is_tie = tied.length > 1
+    frontier = frontier_for(winner)
+
+    state =
+      if frontier.nil?
+        "exhausted"
+      elsif !frontier[:dispatchable].empty?
+        "dispatchable"
+      else
+        "in_flight"
+      end
+
+    payload(mode: mode, state: state, roadmap: winner[:slug],
+            frontier_wave: frontier && frontier[:heading],
+            dispatchable: frontier ? frontier[:dispatchable] : [],
+            in_flight: frontier ? frontier[:in_flight] : [],
+            blocked: blocked_for(winner),
+            tie: is_tie,
+            tie_candidates: [])
+  end
+
+  # --- enumerate + parse --------------------------------------------------------
+
+  def roadmap_paths
+    return [] unless @roadmaps_dir && Dir.exist?(@roadmaps_dir)
+    Dir.glob(File.join(@roadmaps_dir, "*.md"))
+       .reject { |p| p.end_with?(".savepoint.md") }
+       .sort
+  end
+
+  def parse_roadmap(path)
+    text = File.read(path)
+    { slug: File.basename(path, ".md"), path: path, waves: parse_waves(section_body(text, "Waves")) }
+  end
+
+  def parse_waves(waves_body)
+    waves = []
+    current = nil
+    waves_body.each_line do |line|
+      stripped = line.chomp.strip
+      if (m = stripped.match(WAVE_HEADING))
+        current = { heading: m[1], entries: [] }
+        waves << current
+      elsif current && (em = stripped.match(ENTRY))
+        current[:entries] << { id: em[2], raw_status: em[3].downcase }
+      end
+    end
+    waves
+  end
+
+  def section_body(text, heading)
+    m = text.match(/^##\s+#{Regexp.escape(heading)}\s*$(.*?)(?=^##\s|\z)/m)
+    m ? m[1] : ""
+  end
+
+  # --- INDEX reconciliation (INDEX wins), applied before classification --------
+
+  def reconcile(parsed_list)
+    parsed_list.each do |c|
+      c[:waves].each do |wave|
+        wave[:entries].each { |entry| entry[:status] = reconcile_status(entry[:id], entry[:raw_status]) }
+      end
+    end
+    parsed_list
+  end
+
+  def reconcile_status(id, raw_status)
+    case index_status_map[id]
+    when "delivered" then "delivered"
+    when "abandoned" then "abandoned"
+    when "queued" then "queued"
+    when :active then raw_status == "delivered" ? "delivering" : raw_status
+    else raw_status
+    end
+  end
+
+  def index_status_map
+    return @index_status_map if defined?(@index_status_map)
+    @index_status_map = {}
+    path = resolved_index_path
+    return @index_status_map unless path && File.exist?(path)
+
+    text = File.read(path)
+    { "Completed" => "delivered", "Abandoned" => "abandoned", "Active" => :active, "Future" => "queued" }.each do |heading, tag|
+      section_body(text, heading).each_line do |line|
+        stripped = line.strip
+        next unless stripped.start_with?("- [")
+        m = stripped.match(/\A-\s*\[(\S+)\s/)
+        next unless m
+        @index_status_map[m[1]] = tag
+      end
+    end
+    @index_status_map
+  end
+
+  def resolved_index_path
+    return @index_path if @index_path
+    return nil unless @roadmaps_dir
+    File.join(File.dirname(@roadmaps_dir), "INDEX.md")
+  end
+
+  # --- liveness ranking (ports plastic-roadmap-continuing's read-time algorithm) -
+
+  def rank_candidates(parsed_list)
+    parsed_list.map do |c|
+      entries = c[:waves].flat_map { |w| w[:entries] }
+      live = entries.any? { |e| %w[delivering blocked].include?(e[:status]) }
+      c.merge(live: live, last_event: last_event_time(c[:path]))
+    end.sort_by { |c| [c[:live] ? 0 : 1, -c[:last_event].to_i, c[:slug]] }
+  end
+
+  def tied_group(ranked)
+    return [] if ranked.empty?
+    top_key = [ranked.first[:live], ranked.first[:last_event].to_i]
+    ranked.select { |c| [c[:live], c[:last_event].to_i] == top_key }
+  end
+
+  def last_event_time(path)
+    ledger_path = RoadmapSavepoint.ledger_path_for(path)
+    if File.exist?(ledger_path)
+      last_line = File.readlines(ledger_path).map(&:strip).reject(&:empty?).last
+      if last_line
+        token = last_line[/\A(\S+)/, 1]
+        begin
+          return Time.iso8601(token) if token
+        rescue ArgumentError
+          # fall through to the Log fallback below
+        end
+      end
+    end
+    log_fallback_time(path)
+  end
+
+  def log_fallback_time(path)
+    body = section_body(File.read(path), "Log")
+    last = body.each_line.map { |l| l.chomp.strip }.select { |l| l.match?(LOG_LINE) }.last
+    return Time.at(0) unless last
+
+    m = last.match(LOG_LINE)
+    y, mo, d = m[1].split("-").map(&:to_i)
+    h, mi = m[2].split(":").map(&:to_i)
+    Time.utc(y, mo, d, h, mi, 0)
+  end
+
+  # --- frontier + dispatchable selection (D-b) ----------------------------------
+
+  def 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) }
+
+      queued = wave[:entries].select { |e| e[:status] == "queued" }
+      delivering = wave[:entries].select { |e| e[:status] == "delivering" }
+
+      # intent-173 ranking-swap seam: value-orders the dispatchable candidates only.
+      ordered = @ranker.rank(queued)
+
+      dispatchable = ordered.each_with_index.map do |e, i|
+        { "id" => e[:id], "scope" => scope_label, "roadmap" => candidate[:slug],
+          "wave" => wave[:heading], "status" => "queued", "rank" => i + 1 }
+      end
+      in_flight = delivering.map do |e|
+        { "id" => e[:id], "roadmap" => candidate[:slug], "wave" => wave[:heading], "status" => "delivering" }
+      end
+
+      return { heading: wave[:heading], dispatchable: dispatchable, in_flight: in_flight }
+    end
+    nil
+  end
+
+  def blocked_for(candidate)
+    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
+  end
+
+  # --- scope + payload -----------------------------------------------------------
+
+  def scope_label
+    m = @roadmaps_dir.to_s.match(%r{/projects/([^/]+)/roadmaps/?\z})
+    m ? "project:#{m[1]}" : "global"
+  end
+
+  def payload(mode:, state:, roadmap:, frontier_wave:, dispatchable:, in_flight:, blocked:, tie:, tie_candidates:)
+    {
+      "generated_for" => "roadmap-next",
+      "mode" => mode,
+      "scope" => scope_label,
+      "state" => state,
+      "roadmap" => roadmap,
+      "frontier_wave" => frontier_wave,
+      "dispatchable_queue" => dispatchable,
+      "in_flight" => in_flight,
+      "blocked" => blocked,
+      "tie" => tie,
+      "tie_candidates" => tie_candidates,
+      "ranking_strategy" => @ranker.name,
+      "generated_at" => @now.utc.iso8601,
+    }
+  end
+end

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/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