@zalom/plastic 1.2.0 → 1.4.0

package/scripts/restore-intent-v1

@@ -0,0 +1,288 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# restore-intent-v1 - restore a completed intent's PROSE to an explicit v1 git ref
+# while preserving its frontmatter GRAPH (sources/chain) as a target-resolved
+# union of the v1 snapshot and the current snapshot (intent 193). This is the
+# ONLY sanctioned way to restore a completed intent to v1; a hand-run whole-file
+# `git checkout`/revert is forbidden (see PLASTIC.md > Terminal immutability),
+# because it cannot tell prose from graph metadata and silently destroys
+# backlinks written after v1 (the 124/131 incident this tool exists to prevent).
+#
+# Usage:
+#   restore-intent-v1 <intent-id> --at <git-ref> [--plastic-home PATH] [--apply] \
+#                      [--skip-links] [--audit-path PATH]
+#
+# Dry-run by default (the OPPOSITE of rebuild-graph/project-links, which default
+# to a real run): this tool is rarer and higher blast-radius, and this exact
+# class of tool already destroyed live store data once. --apply is required to
+# write.
+#
+# Restore-to-v1 runs under the MAINTENANCE lock (PLASTIC.md > Terminal
+# immutability: the maintenance lock covers sanctioned structural move-and-record
+# edits after completion). This tool does NOT acquire, check, or manage that
+# lock itself (fail-open doctrine, intent 111: lock management is the
+# orchestrator's job, never built into a CLI as a trap); it only prints a
+# one-line reminder on --apply.
+#
+# LINKS BLAST RADIUS: an applied restore reprojects `## Links` via
+# scripts/project-links, which is a STORE-WIDE operation with no per-intent
+# scoping (it rewrites `## Links` in every intent under --plastic-home, not only
+# the one being restored). This is announced explicitly before it runs. Pass
+# --skip-links to decline it (the tool then warns loudly that `## Links` is
+# stale until project-links is run by hand).
+#
+# Pure-Ruby (no bash). Graph math lives in lib/restore_intent_v1.rb and reuses
+# lib/graph_rebuild.rb + lib/frontmatter_writer.rb verbatim; this shell does only
+# discovery, git IO, and reporting. Never pushes ~/.plastic.
+
+require "fileutils"
+require "time"
+require "open3"
+
+require_relative "lib/store_discovery"
+require_relative "lib/intent_validator"
+require_relative "lib/graph_rebuild"
+require_relative "lib/frontmatter_writer"
+require_relative "lib/restore_intent_v1"
+
+class RestoreIntentV1CLI
+  DEFAULT_HOME = File.join(Dir.home, ".plastic")
+  PROSE_SIBLINGS = %w[checklist.md outcome.md spec.md plan.md].freeze
+
+  def self.parse_argv(argv)
+    args = argv.dup
+    intent_id = nil
+    opts = { at: nil, plastic_home: DEFAULT_HOME, apply: false, skip_links: false, audit_path: nil }
+    i = 0
+    while i < args.length
+      case args[i]
+      when "--at" then opts[:at] = args[i += 1]
+      when "--plastic-home" then opts[:plastic_home] = args[i += 1]
+      when "--apply" then opts[:apply] = true
+      when "--skip-links" then opts[:skip_links] = true
+      when "--audit-path" then opts[:audit_path] = args[i += 1]
+      else
+        intent_id ||= args[i]
+      end
+      i += 1
+    end
+    [intent_id, opts]
+  end
+
+  def initialize(intent_id, at:, plastic_home: DEFAULT_HOME, apply: false, skip_links: false, audit_path: nil)
+    @intent_id = intent_id
+    @at = at
+    @plastic_home = plastic_home
+    @apply = apply
+    @skip_links = skip_links
+    @audit_path = audit_path
+  end
+
+  attr_reader :intent_id, :at, :plastic_home, :apply, :skip_links, :audit_path
+
+  def run
+    abort_loud("--at is required") if at.nil? || at.to_s.strip.empty?
+    abort_loud("intent id is required") if intent_id.nil? || intent_id.to_s.strip.empty?
+    abort_loud("--at #{at} does not resolve to a commit") unless ref_exists?
+
+    discovery = StoreDiscovery.discover(plastic_home)
+    dir, store_key = find_intent_dir(discovery, intent_id)
+    abort_loud("intent #{intent_id} not found in any known store under #{plastic_home}") if dir.nil?
+
+    base = File.basename(dir)
+    md_path = File.join(dir, "#{base}.md")
+
+    v1_md = git_show(relative(md_path))
+    abort_loud("--at #{at} has no version of #{base}.md; aborting, no write") if v1_md.nil?
+
+    current_md = File.read(md_path)
+    current_fm = IntentValidator.parse_frontmatter_text(current_md)
+    v1_fm = IntentValidator.parse_frontmatter_text(v1_md)
+    abort_loud("v1 snapshot frontmatter unparseable; aborting, no write") if v1_fm.nil? || v1_fm.empty?
+    abort_loud("current frontmatter unparseable; aborting, no write") if current_fm.nil? || current_fm.empty?
+
+    store_index, relocation_map = build_resolution_inputs(discovery)
+
+    graph = RestoreIntentV1.compute_graph(
+      v1_sources: v1_fm["sources"], v1_chain: v1_fm["chain"],
+      current_sources: current_fm["sources"], current_chain: current_fm["chain"],
+      referer_store: store_key, relocation_map: relocation_map, store_index: store_index
+    )
+
+    new_md = RestoreIntentV1.apply_graph(v1_md, desired_sources: graph[:sources], desired_chain: graph[:chain])
+    confirm_graph_write!(new_md, graph)
+
+    other_files = prose_siblings_to_restore(dir)
+
+    prose_changes = other_files.keys.dup
+    prose_changes.unshift("#{base}.md") if new_md != current_md
+
+    puts RestoreIntentV1.render_report(
+      base: base, at: at, prose_changes: prose_changes,
+      v1: { sources: v1_fm["sources"], chain: v1_fm["chain"] },
+      current: { sources: current_fm["sources"], chain: current_fm["chain"] },
+      graph: graph, apply: apply
+    )
+
+    return unless apply
+
+    File.write(md_path, new_md) if new_md != current_md
+    other_files.each { |f, content| File.write(File.join(dir, f), content) }
+
+    puts "Reminder: restore-to-v1 runs under the maintenance lock (PLASTIC.md > Terminal " \
+         "immutability). Confirm the maintenance lock is held before this --apply."
+
+    handle_links_reprojection(base)
+    append_revision(dir, base, graph, files: prose_changes,
+                    before_sources: current_fm["sources"], before_chain: current_fm["chain"])
+  end
+
+  private
+
+  # D8 fail-loud, "unconfirmed graph write": re-parse what was actually computed
+  # for write and assert its sources/chain arrays EQUAL the computed union.
+  # Asserting the substrings "sources:"/"chain:" merely appear somewhere in the
+  # text is NOT a confirmation (a no-op rewrite on a v1 snapshot missing those
+  # keys entirely would still contain neither substring's absence, this checks
+  # the actual parsed values match). Aborts loud, no write, when they do not.
+  def confirm_graph_write!(new_md, graph)
+    written_fm = IntentValidator.parse_frontmatter_text(new_md)
+    written_sources = written_fm ? Array(written_fm["sources"]).map(&:to_s) : nil
+    written_chain = written_fm ? Array(written_fm["chain"]).map(&:to_s) : nil
+
+    return if written_fm && written_sources == graph[:sources] && written_chain == graph[:chain]
+
+    abort_loud(
+      "the rewritten frontmatter does not confirm the computed sources/chain union " \
+      "(expected sources=#{graph[:sources].inspect} chain=#{graph[:chain].inspect}, " \
+      "got sources=#{written_sources.inspect} chain=#{written_chain.inspect}); aborting, no write"
+    )
+  end
+
+  # Every PROSE_SIBLING that existed AT THE V1 REF (not merely that exists NOW)
+  # whose v1 content differs from what is on disk today. Scoping to "exists now"
+  # would silently never restore a sibling deleted after v1 (BLOCKING bug): the
+  # exact class of silent loss this intent exists to prevent, just on a prose
+  # file instead of a graph edge. A sibling deleted since v1 is recreated with
+  # its exact v1 bytes; a sibling that never existed at v1 is left untouched.
+  def prose_siblings_to_restore(dir)
+    other_files = {}
+    PROSE_SIBLINGS.each do |f|
+      path = File.join(dir, f)
+      v1_content = git_show(relative(path))
+      next if v1_content.nil? # did not exist at v1: nothing to restore
+
+      current_content = File.exist?(path) ? File.read(path) : nil
+      other_files[f] = v1_content if v1_content != current_content
+    end
+    other_files
+  end
+
+  # LINKS BLAST RADIUS (D8/Goal 4): reprojection is store-wide, not scoped to
+  # this intent. Announce it unmissably before running it, unless --skip-links
+  # was given, in which case warn loudly that ## Links is now stale.
+  def handle_links_reprojection(base)
+    if skip_links
+      warn "restore-intent-v1: --skip-links given; ## Links across the WHOLE STORE " \
+           "(#{plastic_home}) is now potentially STALE relative to the preserved graph. " \
+           "Rerun `ruby #{File.expand_path("project-links", __dir__)} --plastic-home " \
+           "#{plastic_home}` to reproject it."
+      return
+    end
+
+    puts "restore-intent-v1: reprojecting ## Links STORE-WIDE (every intent under " \
+         "#{plastic_home}, not only #{base}) via project-links..."
+    reproject_links
+  end
+
+  def ref_exists?
+    _out, status = Open3.capture2("git", "-C", plastic_home, "rev-parse", "--verify", "--quiet", "#{at}^{commit}")
+    status.success?
+  end
+
+  def git_show(rel_path)
+    out, status = Open3.capture2("git", "-C", plastic_home, "show", "#{at}:#{rel_path}")
+    status.success? ? out : nil
+  end
+
+  def relative(path)
+    path.delete_prefix("#{plastic_home}/")
+  end
+
+  # id--slug directory resolution: exact id match on the dirname's segment before
+  # the first "--" (matches the convention scripts/doctor.rb already uses), never
+  # a start_with? scan, so "1" never matches "124--...". A bare id present in MORE
+  # THAN ONE store is ambiguous; given this tool's blast radius, abort loud and
+  # name every candidate rather than silently guessing the first one found.
+  def find_intent_dir(discovery, id)
+    matches = []
+    discovery[:stores].each do |s|
+      Dir.children(s[:store]).reject { |e| e.start_with?(".") }.each do |entry|
+        full = File.join(s[:store], entry)
+        next unless File.directory?(full)
+        next unless entry.split("--", 2).first == id.to_s
+
+        matches << [full, s[:key]]
+      end
+    end
+    return matches.first if matches.length <= 1
+
+    candidates = matches.map { |(full, key)| "#{key}:#{File.basename(full)}" }.join(", ")
+    abort_loud(
+      "intent id #{id} is ambiguous: found in more than one store (#{candidates}); " \
+      "aborting, no write. This tool has too much blast radius to guess which one you " \
+      "mean; resolve the collision (rename or relocate one of the intents) before restoring."
+    )
+  end
+
+  # Build the store_index (store_key => bare ids present) and relocation_map
+  # (from every store's INDEX.md ## Relocated log) that GraphRebuild.resolve_ref
+  # needs, using the exact recipe scripts/rebuild-graph already uses.
+  def build_resolution_inputs(discovery)
+    store_index = {}
+    index_texts = {}
+    discovery[:stores].each do |s|
+      store_index[s[:key]] = Dir.children(s[:store]).reject { |e| e.start_with?(".") }
+                                 .select { |e| File.directory?(File.join(s[:store], e)) }
+                                 .map { |e| e.split("--", 2).first }
+      index_texts[s[:key]] = File.exist?(s[:index]) ? File.read(s[:index]) : ""
+    end
+    [store_index, GraphRebuild.build_relocation_map(index_texts)]
+  end
+
+  def reproject_links
+    project_links = File.expand_path("project-links", __dir__)
+    system(RbConfig.ruby, project_links, "--plastic-home", plastic_home)
+    return if $?.success?
+
+    warn "restore-intent-v1: ## Links may now be stale (project-links reprojection failed). " \
+         "Rerun: ruby #{project_links} --plastic-home #{plastic_home}"
+  end
+
+  def append_revision(dir, base, graph, files:, before_sources:, before_chain:)
+    path = File.join(dir, "revisions.md")
+    existing = File.exist?(path) ? File.read(path) : "# revisions.md\n\n"
+    nums = existing.scan(/^## Revision v(\d+)/).flatten.map(&:to_i)
+    n = (nums.max || 0) + 1
+
+    entry = RestoreIntentV1.render_revision_entry(
+      n, at: at, timestamp: Time.now.utc.strftime("%Y-%m-%d-%H:%M"), files: files,
+      before_sources: before_sources, after_sources: graph[:sources],
+      before_chain: before_chain, after_chain: graph[:chain],
+      dropped: graph[:dropped]
+    )
+    File.write(path, "#{existing.chomp}\n\n#{entry}")
+  end
+
+  def abort_loud(message)
+    warn "restore-intent-v1: #{message}"
+    exit 1
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  intent_id, opts = RestoreIntentV1CLI.parse_argv(ARGV)
+  RestoreIntentV1CLI.new(intent_id, **opts).run
+end

package/scripts/roadmap-next

@@ -14,7 +14,9 @@
 #   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.
+# not errors). Exits 2 on a missing required flag. Exits 3 when a roadmap has neither
+# '## Batches' (canonical) nor '## Waves' (legacy) as its grouping heading (intent 196): a
+# malformed roadmap fails loudly, never silently parses as zero entries.
 
 require_relative "lib/roadmap_queue"
 require "json"
@@ -39,6 +41,11 @@ if roadmaps_dir.nil?
 end
 
 reader = RoadmapQueue.new(roadmaps_dir: roadmaps_dir, index_path: index)
-payload = which ? reader.which : reader.queue
+begin
+  payload = which ? reader.which : reader.queue
+rescue RoadmapSavepoint::MissingGroupingHeading => e
+  warn "roadmap-next: #{e.message}"
+  exit 3
+end
 puts JSON.generate(payload)
 exit 0

package/scripts/roadmap-savepoint

@@ -13,6 +13,9 @@
 #   roadmap-savepoint rebuild --roadmap <path>
 #
 # Exits non-zero with a usage line on stderr for an unknown verb or a missing required flag.
+# Exits 3 on rebuild when a roadmap has neither '## Batches' (canonical) nor '## Waves' (legacy)
+# as its grouping heading (intent 196): a malformed roadmap fails loudly, never silently
+# rebuilds an empty ledger.
 
 require_relative "lib/roadmap_savepoint"
 
@@ -53,7 +56,12 @@ when "rebuild"
     usage
     exit 2
   end
-  count = RoadmapSavepoint.rebuild(roadmap)
+  begin
+    count = RoadmapSavepoint.rebuild(roadmap)
+  rescue RoadmapSavepoint::MissingGroupingHeading => e
+    warn "rebuild: #{e.message}"
+    exit 3
+  end
   puts "rebuilt #{count} line#{count == 1 ? '' : 's'}"
   exit 0
 

package/scripts/update.rb

@@ -14,6 +14,7 @@
 
 require_relative "lib/installer_core"
 require_relative "doctor"
+require_relative "lib/config_asks"
 
 class Update < InstallerCore
   PKG = "@zalom/plastic"
@@ -53,11 +54,51 @@ class Update < InstallerCore
       end
       puts "\u{2b06}\u{fe0f}  Updating Plastic #{iv} \u{2192} #{res[:target]}"
       exit_code = perform_switch(res[:target], agent_args(argv))
-      run_post_update_doctor(full: argv.include?("--full-doctor")) if exit_code == 0
+      if exit_code == 0
+        announce_pending_config_asks(agent_key: primary_agent_key(argv))
+        run_post_update_doctor(full: argv.include?("--full-doctor"))
+      end
       exit_code
     end
   end
 
+  # Print any pending config question(s) straight to stdout, right after a
+  # successful perform_switch (the moment the NEW config_asks.yml and
+  # write-config just landed on disk via the target versions own
+  # `install --reinstall`). Informational only, like run_post_update_doctor:
+  # rescued so a crash here can never undo or fail an update that already
+  # succeeded, and never changes the exit code this methods caller returns.
+  #
+  # A manifest that exists but cannot be read or parsed still prints
+  # something visible (the problem itself), it never prints nothing: a
+  # missing manifest is a legitimate quiet no-op, an unreadable one is not.
+  # agent_key defaults to "claude" and should be the agent this update is
+  # actually installing for, so an entry scoped to a different agent is not
+  # announced here.
+  def announce_pending_config_asks(agent_key: "claude", out: $stdout)
+    manifest_problem = ConfigAsks.manifest_error(plastic_home)
+    if manifest_problem
+      out.puts "\nCould not check for pending config questions: #{manifest_problem}"
+      return
+    end
+
+    pending = ConfigAsks.pending(plastic_home, agent_key)
+    return if pending.empty?
+
+    out.puts "\nConfig question(s) introduced by this update:"
+    pending.each do |entry|
+      out.puts "  #{entry["question"]} (id: #{entry["id"]})"
+      Array(entry["options"]).each do |opt|
+        out.puts "    - #{opt["label"]}"
+        out.puts "      #{ConfigAsks.write_config_command(plastic_home, entry["key"], opt["value"])}"
+      end
+      out.puts "    - Not now (keep the default)"
+      out.puts "      #{ConfigAsks.dismiss_command(plastic_home, entry["id"])}"
+    end
+  rescue StandardError => e
+    out.puts "  could not check config asks: #{e.message}"
+  end
+
   # Run doctor after a successful update and print a human-readable summary.
   # Defaults to the fast core tier (agent registration + core files + manifest
   # sync, binary pass|fail, no store walk) so a newcomer's first post-update
@@ -118,6 +159,14 @@ class Update < InstallerCore
     flags.empty? ? ["--claude"] : flags
   end
 
+  # The single agent key this update is installing for, for config_asks
+  # scoping purposes: the first explicitly-flagged agent found in argv, or
+  # "claude" (matches agent_args' own default, and covers --all / no flag).
+  def primary_agent_key(argv)
+    match = agents.find { |a| argv.include?(a[:flag]) }
+    match ? match[:key] : "claude"
+  end
+
   def fetch_dist_tags
     raw = `npm view #{PKG} dist-tags --json 2>/dev/null`
     return nil if raw.nil? || raw.strip.empty?

package/scripts/validate-intent

@@ -16,6 +16,7 @@
 # --home <path> overrides the Plastic home (default: ~/.plastic).
 
 require_relative "lib/intent_validator"
+require_relative "lib/store_discovery"
 
 def plastic_home(args)
   if (i = args.index("--home")) && args[i + 1]
@@ -41,7 +42,8 @@ if intent_dir.nil?
 end
 
 dir = File.expand_path(intent_dir)
-result = IntentValidator.validate(dir, plastic_home: home)
+known_stores = StoreDiscovery.known_slugs(home)
+result = IntentValidator.validate(dir, plastic_home: home, known_stores: known_stores)
 
 if result[:ok]
   puts "OK: #{dir}"

package/scripts/validate-project

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# validate-project - deterministic CLI over ProjectValidator (intent 190).
+#
+# Checks whether a registered project's spawn is structurally complete: the
+# project directory exists, project.yml exists and parses, a root AGENTS.md
+# exists, and the store/ and INDEX.md exist. plastic-project-creating runs
+# this as a self-check before announcing a spawn as done; any agent or human
+# can run it on one slug.
+#
+# Usage:
+#   validate-project <slug> [--home <path>]
+#
+# Exit codes: 0 (structurally complete), 1 (incomplete; report on stderr), 2 (usage).
+# --home <path> overrides the Plastic home (default: ~/.plastic).
+
+require_relative "lib/project_validator"
+
+def plastic_home(args)
+  if (i = args.index("--home")) && args[i + 1]
+    File.expand_path(args[i + 1])
+  else
+    File.expand_path(ENV["PLASTIC_HOME"] || "~/.plastic")
+  end
+end
+
+home = plastic_home(ARGV)
+
+home_value_index = (i = ARGV.index("--home")) ? i + 1 : nil
+slug_index = ARGV.each_index.find do |idx|
+  arg = ARGV[idx]
+  !arg.start_with?("--") && idx != home_value_index
+end
+slug = slug_index && ARGV[slug_index]
+
+if slug.nil?
+  warn "usage: validate-project <slug> [--home <path>]"
+  exit 2
+end
+
+result = ProjectValidator.validate(slug, plastic_home: home)
+
+if result[:ok]
+  puts "OK: #{slug}"
+  exit 0
+end
+
+warn "INCOMPLETE: #{slug}"
+result[:missing].each { |item| warn "missing: #{item}" }
+result[:errors].each { |error| warn error }
+exit 1

package/scripts/write-config

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Usage: write-config <key> <value>
+#        write-config <key> --push <value>
+# Writes a value into the GLOBAL ~/.plastic/config.yml at a dot-notation key,
+# creating intermediate hashes as needed. read-config's missing write-side
+# counterpart. --push appends into an array at that key instead of overwriting
+# it (deduped, creating the array if absent) -- used for dismissal lists like
+# config_asks_dismissed.
+#
+# Concurrency: this is the sole intended writer of the owner's live
+# config.yml, and it can be invoked by more than one agent session at once.
+# The read-modify-write is guarded by an exclusive flock on a sibling lock
+# file held across the whole critical section, and the write itself is a
+# write-to-temp-then-rename in the same directory, so a reader never observes
+# a half-written file and two concurrent writers never lose one another's key.
+#
+# Safety: if config.yml exists but cannot be parsed, or parses into something
+# that is not a key/value mapping, this script refuses to write at all and
+# exits non-zero. Silently treating a broken config.yml as an
+# empty hash (the way read-config, a read-only script, safely can) would
+# rewrite the owner's config.yml from nothing and destroy whatever was in it;
+# a guard must fail milder than the bug it guards against, not worse.
+#
+# Environment:
+#   PLASTIC_HOME -- override ~/.plastic (for testing)
+
+require "yaml"
+require "json"
+require "fileutils"
+
+def usage_abort
+  $stderr.puts "Usage: write-config <key> <value>\n       write-config <key> --push <value>"
+  exit 1
+end
+
+argv = ARGV.dup
+push = false
+if (idx = argv.index("--push"))
+  push = true
+  argv.delete_at(idx)
+end
+
+key, raw_value = argv
+usage_abort if key.nil? || key.empty? || raw_value.nil?
+
+def coerce(raw)
+  JSON.parse(raw)
+rescue JSON::ParserError
+  raw
+end
+
+value = coerce(raw_value)
+
+global_root = ENV.fetch("PLASTIC_HOME", File.expand_path("~/.plastic"))
+config_path = File.join(global_root, "config.yml")
+lock_path = "#{config_path}.lock"
+
+FileUtils.mkdir_p(global_root)
+
+File.open(lock_path, File::CREAT | File::RDWR, 0o644) do |lock_file|
+  lock_file.flock(File::LOCK_EX)
+
+  config =
+    if File.exist?(config_path)
+      begin
+        YAML.safe_load(File.read(config_path)) || {}
+      rescue StandardError => e
+        $stderr.puts "write-config: refusing to overwrite #{config_path}: could not parse it (#{e.message})"
+        exit 1
+      end
+    else
+      {}
+    end
+
+  # A config.yml that parses cleanly but is not a mapping (a bare string, a
+  # top-level list) would otherwise reach the assignment below and die with a
+  # raw IndexError or TypeError backtrace. Same refusal, same clean message:
+  # an unusable config.yml is never written over, and never merely confusing.
+  unless config.is_a?(Hash)
+    $stderr.puts "write-config: refusing to overwrite #{config_path}: it does not hold a key/value mapping (found #{config.class})"
+    exit 1
+  end
+
+  keys = key.split(".")
+  leaf = keys.pop
+  node = keys.reduce(config) { |acc, k| acc[k] ||= {} }
+
+  if push
+    current = node[leaf]
+    current = [] unless current.is_a?(Array)
+    current << value unless current.include?(value)
+    node[leaf] = current
+  else
+    node[leaf] = value
+  end
+
+  tmp_path = "#{config_path}.tmp.#{Process.pid}.#{Time.now.to_f}"
+  File.write(tmp_path, YAML.dump(config))
+  File.rename(tmp_path, config_path)
+
+  puts "#{key} = #{node[leaf].inspect}"
+end

package/skills/agent-advisor/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: plastic-agent-advisor
+description: >-
+  Consult the advisor for expensive reasoning: one-way doors, plans, adversarial
+  review of a plan or conclusion before an irreversible step, a deadlock after two
+  failed attempts, or ranking several plausible options. Use when the user asks for
+  a second opinion, a hard design decision, an architecture review, help breaking a
+  deadlock, or says "ask the advisor". Also sets which advisor is the default when
+  asked ("make Fable my advisor", "switch my advisor", "use the real advisor").
+user-invocable: true
+---
+
+# Agent Advisor
+
+Plastic ships two consultation agents, never dispatched by the auto pipeline, summoned
+only when you decide the reasoning is worth buying:
+
+- **`plastic-advisor`** ("the real advisor"): the frontier model itself, expensive,
+  billed through usage credits. Spawn it for a few rounds on the hardest problem, then
+  close the session.
+- **`plastic-faux-advisor`** ("the imitation advisor"): an ordinary model carrying the
+  same reasoning discipline inline in its own body, so it reasons the same disciplined
+  way at a fraction of the cost. The cheaper default.
+
+## When to consult (and when not to)
+
+Buy a consultation for: decisions with one-way doors (architecture, migration order,
+public contracts); turning a goal plus evidence into a step plan with checks;
+adversarial review of your plan or conclusion before an irreversible step; a deadlock
+after two failed attempts where you cannot say why; ranking several plausible options
+when the ordering decides where you spend the next day.
+
+Never buy a consultation for: anything a tool can answer (search, reading code, running
+tests, documentation), writing code at volume, confirming a decision you already made,
+style or naming a linter would settle, or anything reversible and cheap you have not
+tried first. The full buy/never-buy list, the tier table, and the entry test live in
+`references/advisor-protocol.md`; read it before writing a brief for the first time in
+a session.
+
+## Routing: which advisor answers
+
+1. Read the harness-scoped config: `advisor.claude.default`. If unset, fall back to
+   `advisor.claude.secondary`, then to `plastic-faux-advisor`.
+2. If the user names which advisor they want ("ask the real one", "use Fable", "ask the
+   cheap one"), honor that directly and dispatch `advisor.claude.primary` (default
+   `plastic-advisor`) or `advisor.claude.secondary` (default `plastic-faux-advisor`)
+   accordingly, overriding step 1 for this consultation only.
+3. If `advisor.enabled` reads `false`, neither advisor agent nor this skill is
+   installed; this step should not be reachable, but if it is, tell the user the
+   advisor is disabled and point at "Setting the default" below.
+4. Dispatch the resolved agent with a brief built per `references/advisor-protocol.md`
+   section 4 (natural prose, the block is a completeness check, not a form to fill).
+   State TIER (S, M, or L) and EFFORT explicitly; classify low and prove your way up,
+   never open high "to be safe".
+5. Consume the answer per the protocol's section 5: run the Operating Manual's
+   five-question self-test on the advisor's plan before executing it. Advice is input,
+   not authority; the plan is the advisor's, the outcome is yours.
+
+Read the resolved config value with:
+
+```bash
+ruby ~/.plastic/scripts/read-config advisor.claude.default --project <repo>
+```
+
+(Omit `--project` outside a registered project; falls back to the global value.)
+
+## Setting the default advisor
+
+When asked to change the default ("make Fable my advisor", "switch my advisor", "use
+the cheaper one by default"), present the two options in plain language and write the
+choice:
+
+- **Faux Fable** (`plastic-faux-advisor`, recommended): an ordinary model carrying the
+  frontier reasoning instructions. Much cheaper, available on any plan, reasons in the
+  same disciplined way.
+- **Fable 5** (`plastic-advisor`): the frontier model itself. The strongest reasoning
+  available, billed through usage credits, so summon it for a few rounds and close it.
+
+These are the same two options the installer offers at install and update time. Write
+the choice to `advisor.claude.default` in the global `~/.plastic/config.yml` (or the
+project's `.plastic_store/config.yml` when the user scopes the change to one project):
+read the file as YAML, set `advisor.claude.default` to the agent name (`plastic-advisor`
+or `plastic-faux-advisor`, never a model name or nickname), and write it back. Confirm
+the new default back to the user in one line.
+
+## References
+
+- `references/advisor-protocol.md`: the full shipped Advisor Protocol (what to buy,
+  tiers and effort, the entry test, how to write a brief that earns its cost, the
+  answer contract, session economics, anti-patterns). Read it before the first
+  consultation in a session; the second consultation in the same advisor thread costs a
+  fraction of the first, so keep follow-ups on one thread rather than opening a new one.