@zalom/plastic 2.0.0-alpha.9 → 2.0.2

package/scripts/lib/agent_models.rb

@@ -10,37 +10,48 @@
 module AgentModels
   # Claude Code aliases only (never pinned ids, never Fable). Keys are the agent
   # file basenames without the `.md` extension.
+  # The three per-kind node agents (intent 340b, G7c, n2), dispatched by
+  # HarnessAdapter::AGENT_TYPE_BY_KIND. work and research resolve the
+  # executor tier, verify the advisor tier, mirroring RunnerPolicy's
+  # model_role split (327 D12): work and research run on plastic-executor's
+  # own tier, and verify on the lifecycle advisor tier, never the cheap tier.
   TIER_DEFAULTS = {
     "plastic-enforcer" => "opus",
-    "plastic-executor" => "sonnet"
+    "plastic-executor" => "sonnet",
+    "plastic-node-work" => "sonnet",
+    "plastic-node-verify" => "opus",
+    "plastic-node-research" => "sonnet"
   }.freeze
 
-  # The two advisor agents (intent 185 final design): plastic-advisor (the real
-  # advisor, ships `model: fable`) and plastic-faux-advisor (the imitation
-  # advisor, an ordinary model carrying the same reasoning discipline inline,
-  # ships `model: opus`). Both are shipped DEFAULTS in frontmatter, never a
+  # The two consultation agents are Primary Advisor and Secondary Advisor.
+  # Both ship Fable; Primary uses medium effort and Secondary uses high effort.
+  # Both are shipped defaults in frontmatter, never a
   # hard-wired identity: agents.models.claude.<name> (or the legacy flat form)
   # overrides either one through the same install-time frontmatter rewrite
   # every agent override uses. Neither is a lifecycle-stage role: never
-  # dispatched by the auto pipeline, not part of TIER_DEFAULTS. Claude-only for
-  # this release (generate_codex_agents skips both by name; the Codex advisor
-  # case is intent 186, not a permanent exclusion).
-  #
-  # Intent 186 DEFINES the advisor Codex pairing but keeps emission deferred: when the skip is
-  # lifted, plastic-advisor pairs to gpt-5.6-sol at xhigh (the deepest) and plastic-faux-advisor
-  # to gpt-5.6-terra at high (cheaper). Neither is in TIER_DEFAULTS and neither is auto-dispatched.
-  CONSULTATION_AGENTS = %w[plastic-advisor plastic-faux-advisor].freeze
-
-  # Codex reasoning-effort per tier alias (intent 102a). model_reasoning_effort is a
-  # depth-of-thinking dial independent of model selection (181 line 317-318), so mapping
-  # the tier here never encodes a rotting Codex model id (116 D1). opus is the deepest
-  # reasoning tier -> the deepest generally-safe effort (high, not the model-dependent
-  # xhigh); sonnet the mid execution tier -> medium; haiku the lightest -> low. minimal is
-  # unused.
+  # dispatched by the auto pipeline, not part of TIER_DEFAULTS. Codex installs
+  # generate both advisors with Astra and preserve each role's effort.
+  CONSULTATION_AGENTS = %w[plastic-primary-advisor plastic-secondary-advisor].freeze
+
+  SHIPPED_MODEL_DEFAULTS = TIER_DEFAULTS.merge(
+    "plastic-primary-advisor" => "fable",
+    "plastic-secondary-advisor" => "fable"
+  ).freeze
+
+  # Codex reasoning effort per tier alias. Model choice and reasoning effort are independent:
+  # aliases select the recommended OpenAI model, while every Plastic role starts at medium.
+  # A valid harness-scoped user override can still choose another effort for one agent.
   EFFORT_BY_ALIAS = {
-    "opus" => "high",
+    "opus" => "medium",
     "sonnet" => "medium",
-    "haiku" => "low"
+    "haiku" => "medium"
+  }.freeze
+
+  DEFAULT_EFFORT = "medium"
+
+  SHIPPED_EFFORT_DEFAULTS = {
+    "plastic-primary-advisor" => "medium",
+    "plastic-secondary-advisor" => "high"
   }.freeze
 
   # Codex model id per tier alias (intent 186). Codex has NO vendor alias layer: every model id
@@ -49,17 +60,26 @@ module AgentModels
   # centralizing every id in ONE map: Plastic owns the alias, so per-role identity costs a single
   # line to refresh on a Codex deprecation plus a Plastic release, and no per-role file carries a
   # raw id. opus (deepest reasoning tier) -> the flagship Sol; sonnet (execution tier) -> the
-  # balanced Terra; haiku (lightest) -> the fast/cheap Luna. Paired with EFFORT_BY_ALIAS so
-  # reasoning roles get a stronger model AND higher effort than executors. This is a shipped
-  # DEFAULT, fully overridable via agents.models.codex.<name>.
+  # balanced Terra; haiku (lightest) -> the fast/cheap Luna. This is a shipped
+  # DEFAULT, fully overridable via agents.models.codex.<name>. Model strength does not change
+  # effort: all three aliases use medium unless agents.efforts.codex.<name> overrides it.
   CODEX_MODEL_BY_ALIAS = {
     "opus" => "gpt-5.6-sol",
     "sonnet" => "gpt-5.6-terra",
     "haiku" => "gpt-5.6-luna"
   }.freeze
 
+  CODEX_MODEL_BY_AGENT = {
+    "plastic-primary-advisor" => "gpt-6-astra",
+    "plastic-secondary-advisor" => "gpt-6-astra"
+  }.freeze
+
   module_function
 
+  def shipped_effort_for(agent)
+    SHIPPED_EFFORT_DEFAULTS.fetch(agent.to_s, DEFAULT_EFFORT)
+  end
+
   # Pull { basename => model } out of a loaded config hash's `agents.models`
   # section, scoped to `harness` ("claude" or "codex"), tolerating a missing or
   # malformed shape. `agents.models` can mix two shapes: legacy FLAT scalar
@@ -93,6 +113,17 @@ module AgentModels
     models_section(global_config, harness: harness).merge(models_section(project_config, harness: harness))
   end
 
+  def effort_override_map(project_config: {}, global_config: {}, harness: "claude")
+    efforts_section(global_config, harness).merge(efforts_section(project_config, harness))
+  end
+
+  def efforts_section(config, harness)
+    agents = config.is_a?(Hash) ? config["agents"] : nil
+    efforts = agents.is_a?(Hash) ? agents["efforts"] : nil
+    section = efforts.is_a?(Hash) ? efforts[harness] : nil
+    section.is_a?(Hash) ? section : {}
+  end
+
   # The model_reasoning_effort for a Plastic tier alias, or nil for any value that is not
   # one of the three shipped aliases (the caller treats nil as a literal Codex model id).
   def effort_for(value)
@@ -104,4 +135,11 @@ module AgentModels
   def codex_model_for(value)
     CODEX_MODEL_BY_ALIAS[value.to_s]
   end
+
+  def shipped_model_for(agent, harness: "claude")
+    value = SHIPPED_MODEL_DEFAULTS[agent.to_s]
+    return value unless harness.to_s == "codex"
+
+    CODEX_MODEL_BY_AGENT[agent.to_s] || codex_model_for(value) || value
+  end
 end

package/scripts/lib/arm.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require_relative "store_layout"
 require "digest"
 require "fileutils"
 require_relative "lock"
@@ -10,13 +11,14 @@ require_relative "savepoint"
 
 # Arm - how an auto team takes an intent and gives it back (intent 307).
 #
-# Three durable facts make a delivery: the delivery lock in the intent
-# directory (who owns it), the code worktree under the project repo (where
-# the code lands), and the per-session pointer in the global store's `.tmp/`
-# (which intent this session records into; a day id means the day ledger).
-# Before 2.0 a fourth thing, a `/tmp` bridge JSON, cached all three plus a
-# stage snapshot; ruling 6 of intent 296 retired it, and this module is what
-# replaced the bridge's arm, disarm, and repair methods (removed in 2.0, intent 307).
+# Two durable facts make a delivery: the delivery lock in the intent
+# directory says who delivers, and the code worktree under the project repo
+# says where the code lands. A conversation session's tmp directory under
+# the global store's `.tmp/` says only that a session started; it names no
+# intent. This module carries the
+# arm, disarm, and repair operations (intent 307); the pure INDEX/project-config
+# helpers that once sat alongside them on a shared-helpers module now live on
+# IndexEntry and ProjectConfig (intent 344).
 #
 # Pure and dependency-injected: every path and clock is an argument, every git
 # call goes through an injected runner, and the only environment read is the
@@ -32,7 +34,7 @@ module Arm
   end
 
   # Deterministic, session-less key derived from the store and the intent id,
-  # for headless runs that carry no session id at all (moved from Bridge).
+  # for headless runs that carry no session id at all.
   def derive_key(store, intent_id)
     "auto-" + Digest::SHA256.hexdigest("#{store}/#{intent_id}")[0, 10]
   end
@@ -62,12 +64,12 @@ module Arm
   end
 
   def global_store(home)
-    File.join(File.expand_path(home), ".plastic", "store")
+    Plastic::StoreLayout.global_store(File.join(File.expand_path(home), ".plastic"))
   end
 
   # The minimal hash Worktree.provision, release, and finish consume: the
   # intent block plus, when asked, the derived worktree block.
-  def bridge_hash(intent_dir:, home: Dir.home, with_worktree: true)
+  def delivery(intent_dir:, home: Dir.home, with_worktree: true)
     dir = File.expand_path(intent_dir)
     data = {
       "intent" => { "id" => intent_id_for(dir), "dir" => File.basename(dir), "store" => store_for(dir) },
@@ -79,12 +81,7 @@ module Arm
   # `{code, code_branch, provisioned}` derived from projects.yml and the
   # intent id: the same path provision creates, `provisioned` iff it exists.
   def worktree_block(intent_dir:, home: Dir.home)
-    dir = File.expand_path(intent_dir)
-    store = store_for(dir)
-    h = home_for(dir, home: home)
-    slug = Worktree.slug_for_store(store, home: h)
-    p = Worktree.paths(slug: slug, intent_id: intent_id_for(dir),
-                       intent_slug: Worktree.slug_from_dir(dir), home: h)
+    p = code_paths(intent_dir: intent_dir, home: home)
     code = p["code"]
     provisioned = !blank?(code) && Dir.exist?(code)
     {
@@ -94,78 +91,78 @@ module Arm
     }
   end
 
-  # --- the pointer -------------------------------------------------------------
-
-  def pointer_path(session, home:)
-    store = global_store(home)
-    SessionLedger.pointer_path(store, SessionLedger.short_session_id(nil, session))
-  end
-
-  def read_pointer(session, home:)
-    path = pointer_path(session, home: home)
-    File.exist?(path) ? File.read(path).strip : nil
+  # The code worktree path and branch this intent would have, whether or not
+  # the worktree exists on disk (blank code for a store-only project).
+  def code_paths(intent_dir:, home: Dir.home)
+    dir = File.expand_path(intent_dir)
+    h = home_for(dir, home: home)
+    slug = Worktree.slug_for_store(store_for(dir), home: h)
+    Worktree.paths(slug: slug, intent_id: intent_id_for(dir),
+                   intent_slug: Worktree.slug_from_dir(dir), home: h)
   end
 
-  def write_pointer(session, value, home:)
+  # Owner rule 2026-08-31: has this session already started a conversation?
+  # A conversation session's tmp directory is made at boot under the global
+  # store's `.tmp/`; a dispatched or headless session (a derived key) never
+  # gets one. Reads only; rescues to false (fail open: a broken store must
+  # never block a legitimate delivery).
+  def started_session?(session, home:)
     store = global_store(home)
-    SessionLedger.ensure_tmp_root(store)
-    path = pointer_path(session, home: home)
-    FileUtils.mkdir_p(File.dirname(path))
-    File.write(path, "#{value}\n")
-    path
+    Dir.exist?(SessionLedger.session_tmp_dir(store, SessionLedger.short_session_id(nil, session)))
+  rescue StandardError
+    false
   end
 
   # --- arm ---------------------------------------------------------------------
 
   # Take an intent for `session`: acquire delivery.lock (stamped with the run
-  # mode and the provenance the caller knows), provision the code worktree
-  # (fail-open for a global-only or non-git intent), and point the session at
-  # the intent. Returns `{status:, lock:, worktree:, session:, pointer:}`.
-  # A held, stale, excluded, or corrupt lock returns that status with the
-  # lock data read and touches nothing.
+  # mode and the provenance the caller knows) and provision the code worktree
+  # (fail-open for a global-only or non-git intent). Returns
+  # `{status:, lock:, worktree:, session:}`. A held, stale, excluded, or
+  # corrupt lock returns that status with the lock data read and touches
+  # nothing.
   def arm(intent_dir:, session:, mode: "auto", home: Dir.home, harness: nil,
           agent: nil, model: nil, thread: nil, now: Time.now, runner: Worktree::ShellRunner.new,
-          host: Socket.gethostname)
+          host: Socket.gethostname, allow_inline: false)
     raise ArgumentError, "mode must be auto or guided" unless %w[auto guided].include?(mode.to_s)
     dir = File.expand_path(intent_dir)
     key = resolve_session(session, store: store_for(dir), intent_id: intent_id_for(dir))
     h = home_for(dir, home: home)
 
+    # Owner rule 2026-08-31: the main session never delivers an intent inline.
+    # A conversation session (its tmp directory already exists under the
+    # global store) arming an intent it does not already hold the lock for is
+    # inline delivery and is refused BEFORE any lock is taken. Re-arming the
+    # intent it already holds stays idempotent. A dispatched or headless
+    # session has no tmp directory and arms freely. --allow-inline is the
+    # explicit owner override.
+    if !allow_inline && started_session?(key, home: h) && !Lock.holds?(dir, session: key)
+      return { status: :inline_refused, lock: nil, worktree: nil, session: key }
+    end
+
     status, lock = Lock.acquire(dir, session: key, host: host, now: now,
                                 harness: harness, agent: agent, model: model,
                                 thread: thread, run_mode: mode.to_s)
     unless %i[acquired owned].include?(status)
-      return { status: status, lock: lock, worktree: nil, session: key, pointer: nil }
+      return { status: status, lock: lock, worktree: nil, session: key }
     end
 
-    data = bridge_hash(intent_dir: dir, home: h, with_worktree: false)
+    data = delivery(intent_dir: dir, home: h, with_worktree: false)
     begin
       Worktree.provision(data, home: h, runner: runner)
     rescue StandardError => e
       warn "plastic: worktree provision raised, continuing unprovisioned: #{e.message}"
     end
 
-    # The pointer is what the capture and record hooks read; they key on the
-    # harness's real session id, so a derived key gets no pointer (nothing would
-    # ever read it). A pointer failure warns and never undoes an acquired lock.
-    pointer = nil
-    unless key == derive_key(store_for(dir), intent_id_for(dir))
-      begin
-        pointer = write_pointer(key, intent_id_for(dir), home: h)
-      rescue StandardError => e
-        warn "plastic: session pointer not written (#{e.message}); the lock is held regardless"
-      end
-    end
     { status: status, lock: lock, worktree: worktree_block(intent_dir: dir, home: h),
-      session: key, pointer: pointer }
+      session: key }
   end
 
   # --- disarm ------------------------------------------------------------------
 
-  # Give the intent back: remove the worktree (when `remove`), release the
-  # lock as its recorded owner (falling back to `session`), and reset the
-  # session pointer to today's day id when it named this intent. Returns
-  # the lock release status (:released, :none, :not_owner, or :raised).
+  # Give the intent back: remove the worktree (when `remove`) and release the
+  # lock as its recorded owner (falling back to `session`). Returns the lock
+  # release status (:released, :none, :not_owner, or :raised).
   def disarm(intent_dir:, session:, home: Dir.home, runner: Worktree::ShellRunner.new,
              remove: true, now: Time.now)
     dir = File.expand_path(intent_dir)
@@ -173,45 +170,36 @@ module Arm
     key = resolve_session(session, store: store_for(dir), intent_id: intent_id_for(dir))
 
     begin
-      Worktree.release(bridge_hash(intent_dir: dir, home: h), home: h, runner: runner, remove: remove)
+      Worktree.release(delivery(intent_dir: dir, home: h), home: h, runner: runner, remove: remove)
     rescue StandardError => e
       warn "plastic: worktree release raised, continuing: #{e.message}"
     end
 
     lock = Lock.read(dir)
     owner = lock && !blank?(lock["owner_session"]) ? lock["owner_session"] : key
-    release_status = begin
+    begin
       Lock.release(dir, session: owner)
     rescue StandardError => e
       warn "plastic: delivery lock release raised for #{dir}, continuing: #{e.message}"
       :raised
     end
-
-    begin
-      reset_pointer(key, intent_id_for(dir), home: h, now: now)
-    rescue StandardError => e
-      warn "plastic: session pointer not reset (#{e.message})"
-    end
-    release_status
-  end
-
-  # Point the session back at the day ledger, but only when it names `intent_id`.
-  def reset_pointer(session, intent_id, home:, now: Time.now)
-    current = read_pointer(session, home: home)
-    return false unless current == intent_id.to_s
-    write_pointer(session, SessionLedger.day_id(now), home: home)
-    true
   end
 
   # --- repair ------------------------------------------------------------------
 
-  # One idempotent repair (the lock half of the bridge's repair, removed in 2.0):
+  # A stale foreign lock is reclaimed only by an audited owner step, never by
+  # the session that found it.
+  def stale_hint(intent_id)
+    "reclaiming a stale lock is the owner's audited step; plastic auto lock status #{intent_id} shows it"
+  end
+
+  # One idempotent repair (the lock half of the repair path):
   # remove a corrupt lock, back off from a fresh foreign lock (`held`), report
   # a stale foreign lock (`stale`) for the explicit reclaim verb, keep and
   # enrich an own lock, heartbeat a delegated one, acquire when none, and
   # provision the worktree so the repaired intent has its checkout.
   def repair(intent_dir:, session:, home: Dir.home, now: Time.now, harness: nil,
-             agent: nil, model: nil, thread: nil, run_mode: nil, hint_harness: nil,
+             agent: nil, model: nil, thread: nil, run_mode: nil,
              runner: Worktree::ShellRunner.new)
     dir = File.expand_path(intent_dir)
     h = home_for(dir, home: home)
@@ -231,11 +219,18 @@ module Arm
       end
       return { "status" => "stale", "owner" => lock["owner_session"],
                "actions" => actions, "session" => key,
-               "hint" => "run #{Lock.skill_ref('plastic-doctor', harness: hint_harness || harness)} " \
-                         "reclaim the lock to take over with an audit" }
+               "hint" => stale_hint(intent_id_for(dir)) }
     end
 
-    mode = blank?(run_mode) ? (lock && lock["run_mode"]) : run_mode.to_s
+    # A lock rebuilt from nothing (none, or a corrupt one removed) is an auto
+    # delivery's lock again; a kept lock keeps whatever mode it had.
+    mode = if !blank?(run_mode)
+      run_mode.to_s
+    elsif lock
+      lock["run_mode"]
+    else
+      "auto"
+    end
     if lock
       if lock["owner_session"].to_s == key.to_s
         lock_data = lock.dup
@@ -259,7 +254,7 @@ module Arm
     end
 
     begin
-      Worktree.provision(bridge_hash(intent_dir: dir, home: h, with_worktree: false), home: h, runner: runner)
+      Worktree.provision(delivery(intent_dir: dir, home: h, with_worktree: false), home: h, runner: runner)
     rescue StandardError => e
       warn "plastic: worktree provision raised during repair, continuing unprovisioned: #{e.message}"
     end
@@ -268,16 +263,4 @@ module Arm
 
     { "status" => "repaired", "actions" => actions, "lock" => lock_data, "session" => key }
   end
-
-  # The intent directory this session's pointer names, searched in the given
-  # stores in order; nil when the pointer is absent, empty, or a day id.
-  def intent_dir_from_pointer(session, home:, stores:)
-    current = read_pointer(session, home: home)
-    return nil if blank?(current) || SessionLedger.valid_day_id?(current)
-    stores.each do |store|
-      match = Dir.glob(File.join(store, "#{current}--*")).find { |p| File.directory?(p) }
-      return match if match
-    end
-    nil
-  end
 end

package/scripts/lib/atomic_write.rb

@@ -0,0 +1,31 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# AtomicWrite (intent 334, n2, D19r): a sibling-temp-plus-rename write, the
+# same shape as Lock#write (scripts/lib/lock.rb) - a content write is never
+# an in-place truncate, so a crash mid-write can never leave an empty or
+# half-written target on disk. The temp file is a SIBLING in the same
+# directory as the target, never a system tmpdir, because File.rename can
+# raise EXDEV when the temp and the target live on different filesystems.
+# The temp name ends in .lock (post-execution review, non-blocking 5), the
+# same property Lock#write_temp_path documents: an orphan left by a crash
+# between the write and the rename is covered by the store's existing
+# *.lock gitignore rule rather than swept into its git add -A auto-commit.
+#
+# The renamer is injectable so the interrupted-write case (a rename that
+# raises) is testable with dependency injection, never eval or a global
+# (D19r).
+module AtomicWrite
+  module_function
+
+  def write(path, content, renamer: File.method(:rename))
+    dir = File.dirname(path)
+    temp = File.join(dir, ".#{File.basename(path)}.tmp.#{Process.pid}.#{Time.now.to_f}.#{rand(0xFFFFFF)}.lock")
+    File.write(temp, content)
+    renamer.call(temp, path)
+    true
+  rescue StandardError
+    File.delete(temp) if temp && File.exist?(temp)
+    raise
+  end
+end

package/scripts/lib/backup.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "digest"
+require "json"
+require "tmpdir"
+require "zlib"
+require_relative "store_sync"
+require_relative "worktree"
+
+module Plastic
+  module Backup
+    DATABASES = [SearchIndex::NAME, WorkGraph::NAME, ReferenceArchive::NAME].freeze
+    ROOT_FILES = %w[config.yml projects.yml INDEX.md].freeze
+    Missing = Class.new(StandardError)
+
+    def self.dir(home)
+      File.join(home, "backups")
+    end
+
+    def self.list(home)
+      Dir.glob(File.join(dir(home), "plastic-backup--*.tar.gz")).sort
+    end
+
+    def self.call(home, version:, now: Time.now.utc)
+      missing = DATABASES.reject { |name| File.exist?(File.join(home, name)) }
+      raise Missing, missing.join(", ") unless missing.empty?
+
+      Worktree.ensure_gitignored(home, "backups/")
+      Dir.mktmpdir("plastic-backup") do |work|
+        DATABASES.each { |name| Sqlite.call(File.join(home, name), "VACUUM INTO #{Sqlite.quote(File.join(work, name))};", readonly: true) }
+        FileUtils.cp(ROOT_FILES.map { |name| File.join(home, name) }.select { |path| File.exist?(path) }, work)
+        File.write(File.join(work, "manifest.json"), JSON.pretty_generate(manifest(work, version, now)))
+        pack(work, File.join(dir(home), "plastic-backup--#{now.strftime("%Y%m%dT%H%M%SZ")}.tar.gz"))
+      end
+    end
+
+    def self.manifest(work, version, now)
+      files = Dir.children(work).sort.map do |name|
+        path = File.join(work, name)
+        {"name" => name, "bytes" => File.size(path), "sha256" => Digest::SHA256.file(path).hexdigest}
+      end
+      {"version" => version, "at" => now.strftime("%Y-%m-%dT%H:%M:%SZ"), "files" => files}
+    end
+
+    def self.pack(work, archive)
+      require "rubygems"
+      require "rubygems/package"
+      FileUtils.mkdir_p(File.dirname(archive))
+      draft = "#{archive}.tmp"
+      Zlib::GzipWriter.open(draft) do |gzip|
+        Gem::Package::TarWriter.new(gzip) do |tar|
+          Dir.children(work).sort.each do |name|
+            path = File.join(work, name)
+            tar.add_file_simple(name, 0o644, File.size(path)) { |entry| IO.copy_stream(path, entry) }
+          end
+        end
+      end
+      File.rename(draft, archive)
+      archive
+    ensure
+      FileUtils.rm_f(draft.to_s)
+    end
+  end
+end

package/scripts/lib/cli/command.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "output"
+require_relative "scope"
+
+module Plastic
+  class CLI
+    class Command
+      OK = 0
+      FAILED = 1
+      USAGE = 2
+      REFUSED = 3
+
+      Usage = Class.new(StandardError)
+      Refusal = Class.new(StandardError)
+      Failure = Class.new(StandardError)
+
+      def self.call(...)
+        command = new(...)
+        command.validate_scope
+        command.call
+        command.flush
+        OK
+      rescue OptionParser::ParseError, Scope::UnknownProject, Usage => e
+        command.output.usage(e.message, self::USAGE_LINE)
+        USAGE
+      rescue Refusal => e
+        command.output.refused(e.message)
+        REFUSED
+      rescue Failure => e
+        command.output.failed(e.message)
+        FAILED
+      end
+
+      attr_reader :output
+
+      def initialize(argv, out:, err:, env: ENV, home: Dir.home, directory: Dir.pwd)
+        @argv = argv.dup
+        @env = env
+        @home = home
+        @directory = directory
+        @output = Output.new(out: out, err: err, json: @argv.include?("--json"))
+      end
+
+      def call
+        raise NoMethodError, "#{self.class} must define call"
+      end
+
+      def validate_scope
+        scope.slug if @argv.grep(/\A--project(?:=|$)/).any?
+      end
+
+      def flush
+        @output.project = scope.slug
+        @output.flush(json: options[:json])
+      end
+
+      private
+
+      def options
+        return @options if @options
+
+        @options = {}
+        parser.parse!(@argv)
+        @options
+      end
+
+      def arguments
+        options
+        @argv
+      end
+
+      def parser
+        @parser ||= OptionParser.new do |o|
+          o.banner = self.class::USAGE_LINE
+          o.on("--json") { @options[:json] = true }
+          o.on("--project SLUG") { |slug| @options[:project] = slug }
+          switches(o)
+        end
+      end
+
+      def switches(_parser)
+        nil
+      end
+
+      def scope
+        @scope ||= Scope.new(env: @env, home: @home, slug: options[:project], directory: @directory)
+      end
+    end
+  end
+end

package/scripts/lib/cli/commands/auto.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "subcommand_list"
+
+# `plastic auto` - the list of `plastic auto ...` subcommands, straight out of
+# the table.
+module Plastic
+  class CLI
+    module Commands
+      class Auto < SubcommandList
+        USAGE_LINE = "plastic auto SUBCOMMAND [options]"
+        PREFIX = "auto"
+        NEXT = "plastic auto take ID"
+        BECAUSE = "taking the intent is what every other auto subcommand needs first"
+      end
+    end
+  end
+end