@zalom/plastic 1.0.3 → 1.1.1

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/store_provisioning.rb

@@ -14,7 +14,7 @@ require "yaml"
 # `project.yml` (from templates/project.yml). Re-running never clobbers existing
 # files. The logic was migrated here from the orphaned
 # `InstallerCore#bootstrap_project_store` so there is one definition that the
-# `provision-project-store` CLI, the `plastic-add-project-store` skill, the
+# `provision-project-store` CLI, the `plastic-store-provisioning` skill, the
 # doctor fix hint, and the project skills all consult.
 #
 # Pure filesystem and dependency-injected: `provision` accepts an injectable

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

@@ -13,7 +13,7 @@
 # IntentValidator (exit non-zero if not born complete).
 #
 # It does NOT touch INDEX.md, git, or project creation: those remain skill/agent
-# responsibilities (see plastic-creating-intent).
+# responsibilities (see plastic-intent-creating).
 #
 # Usage:
 #   new-intent --store <store_path> --intent "<one-line>" --slug <slug> \
@@ -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

package/scripts/roadmap-savepoint

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# roadmap-savepoint - deterministic CLI over RoadmapSavepoint (intent 134).
+#
+# The plastic-roadmap skill verbs and the coordinator flows call this instead of hand-writing
+# ledger lines. append is idempotent on the (event, detail) pair; rebuild is the one operation
+# allowed to overwrite the ledger, reconstructing it from the roadmap's own `## Log`.
+#
+# Usage:
+#   roadmap-savepoint append --roadmap <path> --event <event> --detail "<text>"
+#   roadmap-savepoint rebuild --roadmap <path>
+#
+# Exits non-zero with a usage line on stderr for an unknown verb or a missing required flag.
+
+require_relative "lib/roadmap_savepoint"
+
+def opt(args, name)
+  (i = args.index(name)) && args[i + 1]
+end
+
+def usage
+  warn "Usage: roadmap-savepoint append --roadmap <path> --event <event> --detail \"<text>\""
+  warn "       roadmap-savepoint rebuild --roadmap <path>"
+end
+
+verb = ARGV.shift
+
+case verb
+when "append"
+  roadmap = opt(ARGV, "--roadmap")
+  event = opt(ARGV, "--event")
+  detail = opt(ARGV, "--detail")
+  if roadmap.nil? || event.nil? || detail.nil?
+    warn "append: pass --roadmap <path> --event <event> --detail \"<text>\""
+    usage
+    exit 2
+  end
+  begin
+    wrote = RoadmapSavepoint.append(roadmap, event, detail)
+    puts wrote ? "appended #{event}  #{detail}" : "no-op (already recorded): #{event}  #{detail}"
+    exit 0
+  rescue ArgumentError => e
+    warn "append: #{e.message}"
+    exit 2
+  end
+
+when "rebuild"
+  roadmap = opt(ARGV, "--roadmap")
+  if roadmap.nil?
+    warn "rebuild: pass --roadmap <path>"
+    usage
+    exit 2
+  end
+  count = RoadmapSavepoint.rebuild(roadmap)
+  puts "rebuilt #{count} line#{count == 1 ? '' : 's'}"
+  exit 0
+
+else
+  warn "roadmap-savepoint: unknown verb #{verb.inspect}. Use append|rebuild."
+  usage
+  exit 2
+end

package/scripts/{versions.rb → rollback.rb}

@@ -2,20 +2,24 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-# Plastic — `versions` verb. Runs via `npx @zalom/plastic versions` (bin/plastic.js) or directly.
-# Usage: ruby scripts/versions.rb [--downgrade [--version <v>] | --upgrade] [--help]
+# Plastic — `rollback` verb. Runs via `npx @zalom/plastic rollback` (bin/plastic.js) or directly.
+# Usage: ruby scripts/rollback.rb [--version <v> [--downgrade | --upgrade]] [--help]
 #
 # Local time-machine over the append-only versions.json ledger. Navigates ONLY versions you
 # have actually run (the ledger), never npm's full list — fetching brand-new versions is
 # `update`'s job. Lets you roll back to a known-good build after a bad release.
-#   - no flag                  print the ledger table (and offer to continue a rollback)
-#   - --downgrade              step back one version in your history
-#   - --downgrade --version V  jump to a specific previously-run version
-#   - --upgrade                step forward one version (after a rollback)
+#   - no flag                        read-only: print the version-history table, never switch
+#   - --version V                    switch to a specific previously-run version (direction derived)
+#   - --downgrade --version V        synonym of --version V (direction flag is descriptive only)
+#   - --upgrade --version V          synonym of --version V (direction flag is descriptive only)
+#   - --downgrade / --upgrade alone  no target given: error, no switch
+#
+# Switching always requires an explicit --version V. A rollback tool whose job is safety
+# during a bad release must never switch versions without a named target.
 
 require_relative "lib/installer_core"
 
-class Versions < InstallerCore
+class Rollback < InstallerCore
   PKG = "@zalom/plastic"
 
   def cli(argv = ARGV)
@@ -32,31 +36,24 @@ class Versions < InstallerCore
 
     timeline = version_timeline(ledger)
     current = installed_version || timeline.last
+    explicit = flag_value(argv, "--version")
 
-    if argv.include?("--downgrade")
-      explicit = flag_value(argv, "--version")
-      target = explicit || step_target(timeline, current, :back)
-      return no_target("No earlier version in your history.") unless target
-      unless timeline.include?(target)
-        warn "#{target} is not in your version history. Choose one of: #{timeline.join(", ")}"
+    if explicit
+      unless timeline.include?(explicit)
+        warn "#{explicit} is not in your version history. Choose one of: #{timeline.join(", ")}"
         return 1
       end
-      return switch_to(target, current)
-    elsif argv.include?("--upgrade")
-      target = step_target(timeline, current, :forward)
-      return no_target("No later version in your history. Use `update` for new releases.") unless target
-      return switch_to(target, current)
+      return switch_to(explicit, current)
     end
 
-    # No flag: show the table, and detect an in-progress rollback.
-    print_table(ledger, current)
-    if ledger.last && ledger.last["action"] == "downgrade"
-      prev = step_target(timeline, current, :back)
-      if prev && $stdin.tty?
-        print "\nYou recently rolled back. Go back further to #{prev}? [y/N]: "
-        return switch_to(prev, current) if ($stdin.gets&.strip || "").downcase.start_with?("y")
-      end
+    if argv.include?("--downgrade") || argv.include?("--upgrade")
+      warn "An explicit target is required: pass --version <v>. Run `rollback` with no " \
+           "flags to see your version history and pick a target."
+      return 1
     end
+
+    # No flags at all: read-only. Print the table and stop; never switch, never prompt.
+    print_table(ledger, current)
     0
   end
 
@@ -93,11 +90,6 @@ class Versions < InstallerCore
     argv[i + 1]
   end
 
-  def no_target(msg)
-    puts msg
-    0
-  end
-
   def switch_to(target, current)
     action = action_for(target, current)
     puts "#{action == "downgrade" ? "\u{23ea}" : "\u{23e9}"}  #{current} \u{2192} #{target} (#{action})"
@@ -119,23 +111,23 @@ class Versions < InstallerCore
   def show_help
     puts <<~HELP
 
-      plastic versions — manage and roll back your local Plastic versions
+      plastic rollback — read installed and available versions, and switch on request
 
       Usage:
-        npx @zalom/plastic versions [options]
+        npx @zalom/plastic rollback [options]
 
       Options:
-        (none)                  Show the version-history table
-        --downgrade             Roll back one version in your history
-        --downgrade --version V Roll back to a specific previously-run version
-        --upgrade               Step forward one version in your history
-        -h, --help              Show this help
+        (none)                    Show the version-history table (read-only, no switch)
+        --version V                Switch to version V (direction derived automatically)
+        --downgrade --version V    Synonym of --version V
+        --upgrade --version V      Synonym of --version V
+        -h, --help                 Show this help
 
-      Navigates only versions you have already run (the append-only ledger). To move to a
-      brand-new release, use `update`.
+      Switching always requires an explicit --version V. Navigates only versions you have
+      already run (the append-only ledger). To move to a brand-new release, use `update`.
 
     HELP
   end
 end
 
-exit(Versions.new(package_root: ENV["PLASTIC_PACKAGE_ROOT"] || File.expand_path("..", __dir__)).cli(ARGV)) if $PROGRAM_NAME == __FILE__
+exit(Rollback.new(package_root: ENV["PLASTIC_PACKAGE_ROOT"] || File.expand_path("..", __dir__)).cli(ARGV)) if $PROGRAM_NAME == __FILE__

package/scripts/update.rb

@@ -164,7 +164,7 @@ class Update < InstallerCore
       Behaviour:
         No flag advances to the next version on your current channel. Switching toward a
         more stable channel is frictionless; switching toward bleeding edge is confirmed.
-        Use `versions` to roll back to a previously-installed version.
+        Use `rollback` to roll back to a previously-installed version.
 
     HELP
   end

package/skills/_active-intent-gate.md

@@ -13,7 +13,7 @@ Before proceeding, resolve the active intent:
    - Look under `## Active` for intent entries
    - If exactly one active intent → use it
    - If multiple active intents → ask user which one
-   - If no active intent → refuse: "No active intent. Create one first with /plastic-creating-intent"
+   - If no active intent → refuse: "No active intent. Create one first with /plastic-intent-creating"
 
 3. **Resolve paths:**
    - Intent directory: `{store}/store/{id}--{slug}/`

package/skills/_decision-tables.md

@@ -0,0 +1,50 @@
+## Numbered Decision Tables
+
+The shared procedure for collecting owner rulings during any stage (Why, How, Exec).
+Any stage skill that needs the owner to choose between options or rule on a batch of
+open questions follows this procedure instead of improvising its own format.
+
+Read this when a stage skill's own text says to.
+
+### The procedure
+
+1. **Collect the candidate decisions.** Gather every open question or option set that
+   needs an owner ruling right now. Do not present them one at a time across separate
+   messages; batch them into a single collection first.
+
+2. **Present exactly ONE table.** Its first column is the row number. One decision per
+   row. Add a recommendation column stating the agent's recommended choice and a short
+   reason. Example shape:
+
+   | # | Decision | Recommendation |
+   |---|---|---|
+   | 1 | Ship the setting as a CLI flag or a config file? | Config file: survives across invocations |
+   | 2 | Retry, circuit breaker, or fallback for the flaky call? | Retry: matches existing error handling elsewhere in this module |
+
+3. **Let the owner rule by row number.** The owner responds with a ruling per row
+   number (e.g. "1: config file, 2: retry"). Do not require prose paragraphs back; a
+   row-number ruling is enough.
+
+4. **Persist each ruling immediately, one at a time.** For every ruling, before moving
+   to the next row, run:
+
+   ```
+   ruby ~/.plastic/scripts/insight-append {intent_dir} "<ruling text>" --stage <stage> --author human
+   ```
+
+   Never batch rulings into a single call and never wait until all rows are ruled to
+   start persisting. `<stage>` is the current stage (Why, How, or Exec). If a ruling
+   supersedes an earlier one already on record, append a second insight that names the
+   superseded decision and states plainly that this ruling supersedes it. Both insights
+   stay on record; the later one wins.
+
+5. **Write the full ruling set to a rulings file.** After the last row is ruled and
+   persisted, write the complete table plus every ruling to
+   `{intent_dir}/resources/rulings--<slug>.md` so the full set is readable in one place
+   alongside the per-row insights.
+
+### Why one table, not a chip per row
+
+A single table lets the owner rule on everything in one pass and reference row numbers
+in their reply. Multiple small prompts force the owner to context-switch per decision
+and make later replies ambiguous about which decision they answer.