@zalom/plastic 2.0.0-alpha.26 → 2.0.0-alpha.28

package/scripts/lib/cli/table.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Plastic::CLI::TABLE (intent 363) - the whole command line in one frozen hash:
+# a command name mapped to the file that holds it, the class inside
+# Plastic::CLI::Commands, and the one line `plastic help` prints beside it.
+#
+# Adding a command is one row here plus one file. `plastic help` reads this
+# hash and loads nothing, so listing the commands costs no command file.
+# test/cli/table_test.rb walks every row, so a half-wired command cannot ship.
+module Plastic
+  class CLI
+    TABLE = {
+      "auto brief" => ["commands/auto_brief", "AutoBrief", "Print an intent's spawn preamble, and the advisor shapes for --role advisor"],
+      "auto lock" => ["commands/auto_lock", "AutoLock", "Inspect, repair, or release an intent's delivery lock"],
+      "auto report" => ["commands/auto_report", "AutoReport", "Print an intent's completion report, then the review-by-risk rules"],
+      "auto take" => ["commands/auto_take", "AutoTake", "Arm an intent's delivery lock for this session"],
+      "auto" => ["commands/auto", "Auto", "List the auto subcommands"],
+      "backup" => ["commands/backup", "Backup", "Write one archive of the three databases and the config"],
+      "checkout" => ["commands/checkout", "Checkout", "Restore missing store files from the databases"],
+      "continue" => ["commands/continue", "Continue", "Show where one project stands and what runs next"],
+      "doctor" => ["commands/doctor", "Doctor", "Diagnose Plastic installation health"],
+      "feedback" => ["commands/feedback", "Feedback", "File a feedback report, body on standard input"],
+      "help" => ["commands/help", "Help", "List the commands and help topics, or show one usage"],
+      "hook" => ["commands/hook", "Hook", "Run one harness hook event through its launcher"],
+      "index" => ["commands/index", "Index", "Rebuild the search index from every markdown file in the stores"],
+      "install" => ["commands/install", "Install", "Install Plastic into this machine's agents"],
+      "intent" => ["commands/intent", "Intent", "List the intent subcommands"],
+      "intent answer" => ["commands/intent_answer", "IntentAnswer", "Answer an intent's needs_decision node"],
+      "intent end" => ["commands/intent_end", "IntentEnd", "Close an intent as delivered or abandoned"],
+      "intent new" => ["commands/intent_new", "IntentNew", "Create a new intent"],
+      "intent note" => ["commands/intent_note", "IntentNote", "Append a savepoint note to an intent"],
+      "intent rule" => ["commands/intent_rule", "IntentRule", "Record a ruling in an intent's Insights"],
+      "intent show" => ["commands/intent_show", "IntentShow", "Print an intent's state screen"],
+      "intent spec" => ["commands/intent_spec", "IntentSpec", "Print an intent's state screen, then the speccing rules"],
+      "intent step" => ["commands/intent_step", "IntentStep", "Run the next ready step of an intent's graph"],
+      "intent verify" => ["commands/intent_verify", "IntentVerify", "Run an intent's merge-gate checks"],
+      "migrate" => ["commands/migrate", "Migrate", "List the migrate subcommands"],
+      "migrate stores" => ["commands/migrate_stores", "MigrateStores", "Move the stores under stores/, behind a full copy of the home"],
+      "next" => ["commands/next", "Next", "Print the next action in one line"],
+      "project" => ["commands/project", "Project", "List the project subcommands"],
+      "project links" => ["commands/project_links", "ProjectLinks", "Project every store's Links sections from frontmatter"],
+      "project list" => ["commands/project_list", "ProjectList", "List every store this machine holds"],
+      "project new" => ["commands/project_new", "ProjectNew", "Register, provision and validate a new project"],
+      "query" => ["commands/query", "Query", "Run one read-only SQL statement on the index"],
+      "render" => ["commands/render", "Render", "Print one markdown file as an HTML page"],
+      "roadmap" => ["commands/roadmap", "Roadmap", "List the roadmap subcommands"],
+      "roadmap check" => ["commands/roadmap_check", "RoadmapCheck", "Check a roadmap's graph for cycles and dangling ids"],
+      "roadmap log" => ["commands/roadmap_log", "RoadmapLog", "Append a savepoint line to a roadmap's ledger"],
+      "roadmap next" => ["commands/roadmap_next", "RoadmapNext", "Name the roadmap most worth continuing"],
+      "roadmap show" => ["commands/roadmap_show", "RoadmapShow", "Print a roadmap's state screen"],
+      "rollback" => ["commands/rollback", "Rollback", "Move to a Plastic version this machine has run before"],
+      "search" => ["commands/search", "Search", "Find text in the stores, ranked, with one excerpt each"],
+      "session commit" => ["commands/session_commit", "SessionCommit", "Commit one verified checklist item"],
+      "session handoff" => ["commands/session_handoff", "SessionHandoff", "Write this session's hand-off into the day ledger"],
+      "session summary" => ["commands/session_summary", "SessionSummary", "Print the day ledger's open items and recent activity"],
+      "session" => ["commands/session", "Session", "List the session subcommands"],
+      "status" => ["commands/status", "Status", "Show active work in every store"],
+      "sync" => ["commands/sync", "Sync", "Bring the store files and the three databases level"],
+      "uninstall" => ["commands/uninstall", "Uninstall", "Remove Plastic from this machine's agents"],
+      "update" => ["commands/update", "Update", "Move Plastic to the next version on its channel"],
+      "version" => ["commands/version", "Version", "Print the installed Plastic version"]
+    }.freeze
+  end
+end

package/scripts/lib/cli.rb

@@ -0,0 +1,94 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "did_you_mean"
+require_relative "cli/table"
+require_relative "cli/command"
+require_relative "cli/output"
+
+# Plastic::CLI (intent 363) - the dispatcher behind bin/plastic. It reads the
+# command table, matches the longest command name the arguments begin with,
+# requires that one file, and calls it. Nothing else is loaded, which is what
+# keeps a call at about 20 milliseconds with RubyGems off.
+#
+# No arguments, or --help, print the command list. --version prints the
+# version. A command's own --help prints that command's usage line, read from
+# the class without building it. An unknown name exits 2 and names the closest
+# command, so a typo never becomes a stack trace.
+module Plastic
+  class CLI
+    FLAGS = {"--version" => "version", "-v" => "version",
+             "--help" => "help", "-h" => "help"}.freeze
+
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(argv, out: $stdout, err: $stderr, env: ENV, home: Dir.home,
+      directory: Dir.pwd, table: TABLE)
+      @argv = argv.dup
+      @out = out
+      @err = err
+      @env = env
+      @home = home
+      @directory = directory
+      @table = table
+    end
+
+    def call
+      matched = match(expanded)
+      return unknown(expanded.first) unless matched
+
+      name, rest = matched
+      return usage(name, rest) if help?(rest)
+
+      command(name).call(rest, out: @out, err: @err, env: @env, home: @home,
+        directory: @directory)
+    end
+
+    def match(argv)
+      [2, 1].each do |width|
+        name = argv.first(width).join(" ")
+        return [name, argv.drop(width)] if @table.key?(name)
+      end
+      nil
+    end
+
+    private
+
+    def expanded
+      return ["help"] if @argv.empty?
+
+      [FLAGS.fetch(@argv.first, @argv.first)] + @argv.drop(1)
+    end
+
+    def help?(rest)
+      rest.any? { |argument| FLAGS[argument] == "help" }
+    end
+
+    def usage(name, rest)
+      Output.new(out: @out, err: @err)
+        .row("usage", command(name)::USAGE_LINE)
+        .flush(json: rest.include?("--json"))
+      Command::OK
+    end
+
+    def command(name)
+      file, const, = @table.fetch(name)
+      require_relative "cli/#{file}"
+      Commands.const_get(const)
+    end
+
+    def unknown(name)
+      suggestions = closest(name)
+      @err.puts "plastic: no command named #{name.inspect}"
+      @err.puts "Closest: #{suggestions.join(", ")}" unless suggestions.empty?
+      @err.puts "Run `plastic help` for the command list."
+      Command::USAGE
+    end
+
+    def closest(name)
+      DidYouMean::SpellChecker.new(dictionary: @table.keys).correct(name)
+    end
+  end
+end

package/scripts/lib/codex_adapter.rb

@@ -70,15 +70,16 @@ module CodexAdapter
   # worktree, never `~/.plastic`), `--output-last-message` at the path the
   # caller names, and a bare `-` so the prompt is read from stdin (row 6.9) -
   # the node input itself never rides in this array.
-  def build_argv(kind:, worktree:, output_last_message:)
-    [
+  def build_argv(kind:, worktree:, output_last_message:, model: nil, effort: nil)
+    argv = [
       "codex", "exec",
       "-C", worktree.to_s,
       "--sandbox", sandbox_mode(kind),
       *add_dir_args(kind: kind, worktree: worktree),
-      "--output-last-message", output_last_message.to_s,
-      "-",
     ]
+    argv += ["--model", model.to_s] unless model.to_s.strip.empty?
+    argv += ["--config", %(model_reasoning_effort="#{effort}")] unless effort.to_s.strip.empty?
+    argv + ["--output-last-message", output_last_message.to_s, "-"]
   end
 
   # matrix row 6.23: the wall-clock bound comes from the KIND's own lease

package/scripts/lib/compact_instructions.rb

@@ -28,7 +28,15 @@ module CompactInstructions
   # as stale, so the block states the shipped numbers and names the two keys as the
   # override instead. It names the hand-off in words and never by path, so it reads
   # correctly whether or not the hand-off writer is installed.
+  # The `@` line is a Claude Code import: the harness reads the named file into the
+  # session. It is the whole of ruling D43, that PLASTIC.md is the only instruction text
+  # Plastic carries. It names the installed copy under the Plastic home, because a bare
+  # `@PLASTIC.md` would resolve against ~/.claude, where no such file exists.
   BODY = <<~MD.freeze
+    Plastic runs from one command, `plastic`. Its instructions are one page, imported here:
+
+    @~/.plastic/PLASTIC.md
+
     Plastic watches this session's context. When the harness reports how much of the
     window is used:
 

package/scripts/lib/day_summary.rb

@@ -8,6 +8,7 @@
 # heartbeat. Never the raw ledger (296 D36). No environment reads; every
 # path is injected.
 
+require_relative "store_layout"
 require "time"
 require_relative "session_ledger"
 require_relative "handoff"
@@ -82,10 +83,10 @@ module DaySummary
   # The global store plus every projects/<slug>/store, each with its INDEX
   # one level up, the way doctor enumerates them.
   def stores(home)
-    list = [[File.join(home, "INDEX.md"), File.join(home, "store")]]
-    projects_root = File.join(home, "projects")
+    list = [[File.join(Plastic::StoreLayout.global_root(home), "INDEX.md"), Plastic::StoreLayout.global_store(home)]]
+    projects_root = Plastic::StoreLayout.projects_root(home)
     if File.directory?(projects_root)
-      Dir.children(projects_root).sort.each do |slug|
+      Plastic::StoreLayout.project_slugs(home).each do |slug|
         list << [File.join(projects_root, slug, "INDEX.md"), File.join(projects_root, slug, "store")]
       end
     end

package/scripts/lib/doctor_core.rb

@@ -8,12 +8,13 @@
 # the store, conventions, intent and CLI halves, so Doctor stays one class with
 # one public surface and one definition of which checks are core (intent 36a).
 
+require_relative "store_layout"
 require "json"
 require "yaml"
 require "time"
 require "digest"
-require "rubygems"
 
+require_relative "version_number"
 require_relative "hook_registry"
 require_relative "compact_instructions"
 
@@ -301,7 +302,7 @@ class Doctor
       return checks
     end
 
-    index_path = File.join(plastic_home, "INDEX.md")
+    index_path = File.join(Plastic::StoreLayout.global_root(plastic_home), "INDEX.md")
     if File.exist?(index_path)
       checks << check(
         category: "global_store", name: "global_index_reachable", status: "pass",
@@ -517,9 +518,6 @@ class Doctor
       checks << hooks_entries_owned_check(settings)
     end
 
-    # skills_exist — flat, hyphen-namespaced personal skills (plastic-<name>/)
-    checks << flat_skills_check(agent_dir, "--claude")
-
     # stray_skills — installed plastic-* skill dir with no manifest entry (a leftover,
     # e.g. an old-name copy after a rename; intent 158a AC15)
     checks << stray_skills_check(agent_dir, "--claude", File.join(agent_dir, "plastic", "manifest.json"))
@@ -630,24 +628,6 @@ class Doctor
     )
   end
 
-  def flat_skills_check(agent_dir, installer_flag)
-    skills_root = File.join(agent_dir, "skills")
-    found = Dir.glob(File.join(skills_root, "plastic-*", "SKILL.md"))
-
-    if !found.empty?
-      check(
-        category: "agent_registration", name: "skills_exist", status: "pass",
-        message: "#{found.size} plastic-* skill(s) installed in #{tilde(skills_root)}"
-      )
-    else
-      check(
-        category: "agent_registration", name: "skills_exist", status: "fail",
-        message: "No plastic-* skills found in #{tilde(skills_root)}",
-        fixable: true, fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest #{installer_flag}"
-      )
-    end
-  end
-
   # Manifest-diff stray-skill check (intent 158a), extended (intent 276) to
   # never vanish on a missing manifest and to name the reserved-prefix rule.
   def stray_skills_check(agent_dir, installer_flag, manifest_path)
@@ -707,9 +687,6 @@ class Doctor
   def check_flat_skills_and_stray(agent_key, agent_dir)
     checks = []
 
-    # For codex/hermes: just check skills exist (no settings.json hooks)
-    checks << flat_skills_check(agent_dir, "--#{agent_key}")
-
     # stray_skills — installed plastic-* skill dir with no manifest entry (a leftover,
     # e.g. an old-name copy after a rename; intent 158a AC15)
     checks << stray_skills_check(agent_dir, "--#{agent_key}", File.join(agent_dir, "plastic", "manifest.json"))
@@ -1061,9 +1038,7 @@ class Doctor
   end
 
   def safe_version(str)
-    Gem::Version.new(str.to_s)
-  rescue ArgumentError
-    nil
+    VersionNumber.parse(str)
   end
 
   def check_core_files(agent_key, include_drift: true)
@@ -1167,7 +1142,7 @@ class Doctor
               "#{tilde(agent_version_path)}: #{agent_version}",
             ],
             fixable: true,
-            fix_hint: "Re-sync the stale harness: npx @zalom/plastic@latest install --reinstall <flag>, or plastic-rollback to a prior version"
+            fix_hint: "Re-sync the stale harness: npx @zalom/plastic@latest install --reinstall <flag>, or `plastic rollback` to a prior version"
           )
         end
       else
@@ -1175,7 +1150,7 @@ class Doctor
           category: "core_files", name: "version_match", status: "warn",
           message: "Agent-side VERSION file not found at #{tilde(agent_version_path)}",
           fixable: true,
-          fix_hint: "Re-sync the stale harness: npx @zalom/plastic@latest install --reinstall <flag>, or plastic-rollback to a prior version"
+          fix_hint: "Re-sync the stale harness: npx @zalom/plastic@latest install --reinstall <flag>, or `plastic rollback` to a prior version"
         )
       end
     end
@@ -1280,7 +1255,7 @@ class Doctor
 
   DISPLAY_HOOK_FIX_HINT = "Re-run the Plastic installer to repair the hook registration: " \
                           "npx @zalom/plastic@<channel> install --reinstall --claude " \
-                          "(plastic-install --repair)".freeze
+                          "(plastic install --reinstall)".freeze
 
   # display_hook_registered (intent 331e, D1, category "display"): the Claude
   # settings carry the plastic-message-display command, on-disk, executable.

package/scripts/lib/doctor_session_ledger.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require_relative "store_layout"
 require "time"
 require_relative "session_ledger"
 
@@ -38,7 +39,7 @@ module DoctorSessionLedger
   def check_session_ledger(scopes: nil, now: Time.now)
     return [] unless scopes.nil? || scopes.include?("global")
 
-    store_dir = File.join(plastic_home, "store")
+    store_dir = Plastic::StoreLayout.global_store(plastic_home)
     orphans = orphaned_session_dirs(store_dir, now)
     shape = day_ledger_shape_problems(store_dir)
 

package/scripts/lib/feedback_report.rb

@@ -18,7 +18,7 @@ require "fileutils"
 # Trust model: this class never sends anything anywhere. `compose` returns a
 # Result carrying a local file path and a browser URL; only the human, in
 # their own authenticated browser, submits it. There is no send method here
-# and there must never be one (see skills/feedback/references/transport-and-privacy.md).
+# and there must never be one (see SECURITY.md).
 class FeedbackReport
   GITHUB_REPO = "zalom/plastic"
   CAP_BYTES = 7500

package/scripts/lib/graph_measure_models.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require_relative "store_layout"
 require "json"
 require "tmpdir"
 require_relative "node_ledger"
@@ -24,7 +25,7 @@ require_relative "agent_models"
 # through `RunnerPolicy.model_for(kind, config:)`, the one place that maps a
 # node's kind to the role the runner actually dispatched it against - never
 # a hand-rolled kind-to-role table, and never `AgentModels::TIER_DEFAULTS`
-# directly, which carries no `plastic-advisor` entry at all (that agent is a
+# directly, which carries no `plastic-primary-advisor` entry at all (that agent is a
 # consultation agent, never auto-dispatched). Adds no second parser:
 # `NodeLedger` owns the transition-line format, `NodeFile` owns the kind
 # envelope and the `KIND_PREFIX` fallback, `RunnerPolicy`/`AgentModels` own
@@ -112,7 +113,8 @@ module GraphMeasureModels
   # purpose - two different silences over the same store, agreeing with
   # each other only by accident.
   def project_config_path(store_dir)
-    File.join(File.dirname(store_dir.to_s), "config.yml")
+    home, slug = Plastic::StoreLayout.locate(store_dir.to_s)
+    File.join((slug == Plastic::StoreLayout::GLOBAL) ? home : File.dirname(store_dir.to_s), "config.yml")
   end
 
   # --- rendering ---------------------------------------------------------------

package/scripts/lib/index_entry.rb

@@ -10,6 +10,8 @@
 # plain hyphen as the id/title separator on READ; every WRITE still emits the
 # real em dash (D10). The separator is built from the codepoint, not a
 # literal byte, so this file stays em-dash free.
+require_relative "atomic_write"
+
 module IndexEntry
   module_function
 
@@ -22,6 +24,13 @@ module IndexEntry
     line.to_s.match(ENTRY_RE)
   end
 
+  def add_active(index_path, dir_name:, title:)
+    id = dir_name.split("--").first
+    line = "- [#{id} #{EM_DASH} #{title}](store/#{dir_name}/#{dir_name}.md)\n"
+    text = File.read(index_path, encoding: "UTF-8")
+    AtomicWrite.write(index_path, text.sub(/^## Active\n/) { |heading| heading + line })
+  end
+
   # True iff the intent is Active in its store's INDEX.md, which lives at the
   # PARENT of the store/ dir. Non-raising: any failure (missing or unreadable
   # INDEX, bad arg) returns false. `index_active_ids` is a pure-data test