@zalom/plastic 2.0.0-alpha.27 → 2.0.0-alpha.29

package/scripts/hook-record

@@ -10,6 +10,7 @@
 # lands, and calls the session-commit seam when that script exists. Always
 # exits 0 (spec D3).
 
+require_relative "lib/store_layout"
 require "json"
 require "timeout"
 require "fileutils"
@@ -77,7 +78,7 @@ skip_day_ledger = inside_plastic || !intent_dir_abs.nil?
 # --- (c) promote the newest pending line, Item savepoint, seam -------------
 unless skip_day_ledger
   begin
-    store = File.join(plastic_home, "store")
+    store = Plastic::StoreLayout.global_store(plastic_home)
     sid = SessionLedger.short_session_id(nil, session_id)
     today = SessionLedger.day_id
 
@@ -152,7 +153,7 @@ end
 # the heartbeat is not written and no directory is created here either --
 # the session tmp directory, created by session start, is the guard.
 begin
-  store ||= File.join(plastic_home, "store")
+  store ||= Plastic::StoreLayout.global_store(plastic_home)
   sid ||= SessionLedger.short_session_id(nil, session_id)
   if Dir.exist?(SessionLedger.session_tmp_dir(store, sid))
     File.write(SessionLedger.heartbeat_path(store, sid), "#{Time.now.utc.iso8601}\n")

package/scripts/hook-savepoint

@@ -13,6 +13,7 @@
 #
 # Usage: hook-savepoint <plastic_home>   (stdin: the hook JSON)
 
+require_relative "lib/store_layout"
 require "json"
 require_relative "lib/session_ledger"
 require_relative "lib/handoff"
@@ -31,7 +32,7 @@ MESSAGE = "PLASTIC SAVEPOINT - context is being compacted. The hand-off for this
 def resolve_intent(plastic_home, session_id, read_config_path)
   return nil if session_id.strip.empty?
 
-  global_store = File.join(plastic_home, "store")
+  global_store = Plastic::StoreLayout.global_store(plastic_home)
   roots_raw = IO.popen({ "PLASTIC_HOME" => plastic_home }, [read_config_path, "project_roots"],
                        err: File::NULL, &:read).to_s.strip
   project_roots = roots_raw.empty? ? [] : Array(JSON.parse(roots_raw))
@@ -51,7 +52,7 @@ begin
 
   unless plastic_home.empty? || session_id.strip.empty?
     home = File.expand_path(plastic_home)
-    store = File.join(home, "store")
+    store = Plastic::StoreLayout.global_store(home)
     session = SessionLedger.short_session_id(session_id, nil)
     day = Handoff.day_for(store, session, today: SessionLedger.day_id)
     read_config_path = File.expand_path("read-config", __dir__)

package/scripts/hook-session-start

@@ -3,6 +3,7 @@
 # Usage: hook-session-start <index_path> <plastic_home> <mode> [plugin_root]
 # Outputs hook JSON for the session-start hook. Exits silently if nothing to show.
 
+require_relative "lib/store_layout"
 require "json"
 require "date"
 require "yaml"
@@ -58,7 +59,7 @@ end
 # home (~/.plastic) as argument 2; the store lives one level below it. Compose the
 # store exactly once here, so no later line re-derives it and no path can gain a
 # doubled store/ segment.
-store_dir = File.join(plastic_home, "store")
+store_dir = Plastic::StoreLayout.global_store(plastic_home)
 
 # --- Current version ---
 # Read early, before any of the richer INDEX/project parsing below, so the
@@ -154,7 +155,7 @@ begin
       project_path = File.expand_path(info["path"])
       if cwd.start_with?(project_path)
         current_project = { "slug" => slug, "parent" => info["parent"], "path" => project_path }
-        project_index = "#{plastic_home}/projects/#{slug}/INDEX.md"
+        project_index = File.join(Plastic::StoreLayout.project_root(plastic_home, slug), "INDEX.md")
         if File.exist?(project_index)
           p_section = nil
           File.readlines(project_index).each do |pline|
@@ -220,7 +221,7 @@ begin
   if File.exist?(cache_file)
     cache = JSON.parse(File.read(cache_file)) rescue {}
     if cache["updateAvailable"]
-      update_notice = "Plastic update available: #{cache["current"]} -> #{cache["latest"]} — run /plastic-update"
+      update_notice = "Plastic update available: #{cache["current"]} -> #{cache["latest"]} — run `plastic update`"
     end
   end
 
@@ -291,7 +292,7 @@ begin
   if plastic_md && !subagent_session
     if current_project
       slug = current_project["slug"]
-      banner = "Project: #{slug} | Store: ~/.plastic/projects/#{slug}/store/"
+      banner = "Project: #{slug} | Store: #{File.join(Plastic::StoreLayout.project_root(plastic_home, slug), "store").sub(Dir.home, "~")}/"
       if project_active.any? && project_active.first =~ /\[([^\]]+)\].*store\/([\w-]+)\//
         intent_name, dir_name = $1, $2
         intent_id = dir_name.split("--").first

package/scripts/hook-stop

@@ -14,6 +14,7 @@
 #
 # Usage: hook-stop <plastic_home>   (stdin: the hook JSON)
 
+require_relative "lib/store_layout"
 require "json"
 require_relative "lib/stop_gate"
 
@@ -32,7 +33,7 @@ begin
   payload = {} unless payload.is_a?(Hash)
 
   home = File.expand_path(plastic_home)
-  global_store = File.join(home, "store")
+  global_store = Plastic::StoreLayout.global_store(home)
   read_config = File.expand_path("read-config", __dir__)
 
   config_stop_hook = read_config_value("runner.stop_hook", home, read_config)

package/scripts/insight-append

@@ -16,8 +16,7 @@
 # ever reaches Insights.append_insight; the library itself stays untouched,
 # since a tag is a text-level convention, not a new field on the ledger.
 # Doctor's unpromoted_rules check (scripts/doctor.rb) later lists any tagged
-# entry whose exact text no skills/conventions/references/*.md chapter
-# carries yet.
+# entry whose exact text no docs/help/*.md chapter carries yet.
 #
 # Usage:
 #   insight-append <intent_dir> <text> --stage S --author A [--rule]

package/scripts/install.rb

@@ -75,12 +75,14 @@ class Install < InstallerCore
   # they are reported, never re-installed, so the summary line and the Codex
   # trust reminder only ever count agents that actually changed this run.
   def run(selected:, force: false, reinstall: false, ledger_action: nil, argv: ARGV, input: $stdin,
-          already_registered: [])
+          already_registered: [], qmd_runner: QmdSync.default_runner, qmd_detector: QmdSync.method(:detect))
     fresh = !installed?
     mode = fresh ? :install : :update # :update here means "re-sync, skip bootstrap"
 
     distribute(mode)
     bootstrap if fresh
+    git_init_if_absent
+    register_with_qmd(runner: qmd_runner, detector: qmd_detector)
     migrate_advisor_config_file(File.join(plastic_home, "config.yml"))
     apply_config_flags(argv)
 

package/scripts/lib/active_delivery.rb

@@ -60,7 +60,7 @@ module ActiveDelivery
     value.nil? || value.to_s.strip.empty?
   end
 
-  DEFAULT_PROJECT_ROOTS = ["~/.plastic/projects"].freeze
+  DEFAULT_PROJECT_ROOTS = ["~/.plastic/projects", "~/.plastic/stores"].freeze
 
   # The configured project roots (344 n2, D6): the `project_roots` list in
   # `<plastic_home>/config.yml`, each expanded, or the default

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"
@@ -63,7 +64,7 @@ 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

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,85 @@
+# 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.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)
+      end
+
+      def call
+        raise NoMethodError, "#{self.class} must define call"
+      end
+
+      def flush
+        @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 }
+          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

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "intent_command"
+
+# `plastic auto brief` - an intent's spawn preamble (`spawn-preamble`, run
+# through Legacy). `--role advisor` also prints the three shapes an advisor
+# request takes, so a dispatching lead never has to look them up.
+module Plastic
+  class CLI
+    module Commands
+      class AutoBrief < IntentCommand
+        USAGE_LINE = "plastic auto brief ID [--role ROLE] [--json]"
+
+        SCRIPT = "spawn-preamble"
+        AFTER = "plastic auto report ID"
+        BECAUSE = "the report closes the turn the preamble opened"
+
+        ADVISOR_SHAPES =
+          "State the shape you need: a verdict plus the biggest risk for one bounded " \
+          "decision; a stepped plan plus a risk map for a plan or plan review; rival " \
+          "approaches and kill criteria for architecture, one-way doors, or deadlocks."
+
+        def call
+          super
+          @output.row("advisor request shapes", ADVISOR_SHAPES) if role == "advisor"
+        end
+
+        private
+
+        def role
+          options[:role]
+        end
+
+        def switches(parser)
+          parser.on("--role ROLE") { |v| @options[:role] = v }
+        end
+
+        def script_arguments
+          role ? [intent_dir, "--role", role] : [intent_dir]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../legacy"
+
+# `plastic auto lock` - inspects, repairs, or releases an intent's delivery
+# lock (`plastic-lock status|fix|release --intent-dir DIR`, run through
+# Legacy). The verb comes first, then the id, since the verb is what the
+# table's two-token match consumes as part of the command name.
+module Plastic
+  class CLI
+    module Commands
+      class AutoLock < Command
+        USAGE_LINE = "plastic auto lock status|fix|release ID [--json]"
+
+        VERBS = %w[status fix release].freeze
+        AFTER = {"status" => "plastic auto lock fix ID", "fix" => "plastic auto brief ID",
+                 "release" => "plastic session summary"}.freeze
+        BECAUSE = {"status" => "a stale or held lock is repaired by fix, not by re-arming",
+                   "fix" => "a repaired lock is ready for the preamble again",
+                   "release" => "the summary is what a freed lock leads to"}.freeze
+
+        def initialize(argv, runner: nil, **streams)
+          super(argv, **streams)
+          @runner = runner
+        end
+
+        def call
+          raise Usage, "VERB must be one of #{VERBS.join(", ")}" unless VERBS.include?(verb)
+
+          status = legacy.run("plastic-lock", verb, "--intent-dir", intent_dir)
+          raise Failure, "plastic-lock exited #{status}" unless status.zero?
+
+          @output.next_step(AFTER.fetch(verb).sub("ID", id.to_s), because: BECAUSE.fetch(verb))
+        end
+
+        private
+
+        def verb
+          arguments[0]
+        end
+
+        def id
+          arguments[1]
+        end
+
+        def intent_dir
+          dir = scope.intent_dir(id)
+          raise Failure, "no intent #{id.inspect} in #{scope.slug}; plastic status lists the ones that exist" unless dir
+
+          dir
+        end
+
+        def legacy
+          @legacy ||= Legacy.new(env: @env, runner: @runner)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "intent_command"
+
+# `plastic auto report` - an intent's completion report (`agent-report`, run
+# through Legacy), then the review-by-risk rules a lead checks it against.
+module Plastic
+  class CLI
+    module Commands
+      class AutoReport < IntentCommand
+        USAGE_LINE = "plastic auto report ID [--role ROLE] [--json]"
+
+        SCRIPT = "agent-report"
+        AFTER = "plastic auto lock release ID"
+        BECAUSE = "closing the lock is what a delivered or abandoned report leads to"
+
+        REVIEW_RULES = <<~TEXT.chomp
+          Review by risk, boot 3, only when a rule fires; otherwise the green suite is
+          the review. Dispatch the post-execution reviewer when any of these holds:
+          1. the diff touches a path on the risk list (hooks, the lock, the arming
+             module, the installer, a release file).
+          2. a failure-mode matrix row names a test not in the diff, or a test the
+             green run did not execute.
+          3. the completion report carries a status other than delivered, or a
+             non-empty deviations or blockers field.
+          The reviewer returns a pass or fixes; at most one review-fix round, ever.
+        TEXT
+
+        def call
+          super
+          @output.row("review rules", REVIEW_RULES)
+        end
+
+        private
+
+        def role
+          options[:role]
+        end
+
+        def switches(parser)
+          parser.on("--role ROLE") { |v| @options[:role] = v }
+        end
+
+        def script_arguments
+          role ? [intent_dir, "--role", role] : [intent_dir]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "intent_command"
+
+# `plastic auto take` - arms the intent's delivery lock for this session
+# (`plastic-lock arm --intent-dir DIR --mode auto`, run through Legacy).
+module Plastic
+  class CLI
+    module Commands
+      class AutoTake < IntentCommand
+        USAGE_LINE = "plastic auto take ID [--json]"
+
+        SCRIPT = "plastic-lock"
+        AFTER = "plastic auto brief ID"
+        BECAUSE = "the preamble is the live state a taken intent is read from next"
+
+        private
+
+        def script_arguments
+          ["arm", "--intent-dir", intent_dir, "--mode", "auto"]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "version"
+require_relative "../../backup"
+
+module Plastic
+  class CLI
+    module Commands
+      class Backup < Command
+        USAGE_LINE = "plastic backup [--list] [--json]"
+
+        def call
+          options[:list] ? list : write
+        rescue Plastic::Backup::Missing => e
+          @output.next_step("plastic sync", because: "a backup copies the three databases, and sync builds them")
+          raise Failure, "no #{e.message} at #{scope.plastic_home}; run plastic sync"
+        rescue Sqlite::Error => e
+          raise Failure, e.message
+        end
+
+        private
+
+        def switches(parser)
+          parser.on("--list") { options[:list] = true }
+        end
+
+        def write
+          version = Version.new([], out: nil, err: nil, env: @env).found.last
+          @output.row("archive", Plastic::Backup.call(scope.plastic_home, version: version))
+          @output.next_step("plastic backup --list", because: "to restore, unpack the archive into an empty ~/.plastic and run plastic checkout")
+        end
+
+        def list
+          archives = Plastic::Backup.list(scope.plastic_home)
+          archives.each { |path| @output.row(File.basename(path), "#{File.size(path)} bytes  #{File.mtime(path).strftime("%Y-%m-%d %H:%M")}") }
+          @output.row("result", "no backup yet") if archives.empty?
+          @output.next_step("plastic backup", because: "copying backups/ off this machine is your choice; Plastic sends nothing")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../../store_sync"
+
+module Plastic
+  class CLI
+    module Commands
+      class Checkout < Command
+        USAGE_LINE = "plastic checkout [--json]"
+
+        def call
+          home = scope.plastic_home
+          raise Failure, "no databases at #{home}; run plastic sync" unless File.exist?(ReferenceArchive.path(home))
+
+          restored = StoreSync.checkout(home)
+          @output.row("restored", restored.empty? ? "nothing was missing" : restored)
+          @output.next_step("plastic sync --dry-run", because: "checkout restores missing files only; a changed file is never overwritten")
+        rescue Sqlite::Error => e
+          raise Failure, e.message
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../frontier"
+require_relative "../scope"
+
+# `plastic continue` - where one project stands and what runs next: the store it
+# uses, the intents it has open, its liveliest roadmap and that roadmap's
+# frontier, then the step to take and the rule behind it.
+#
+# With no roadmap the first active intent answers instead, so a project that
+# never grew a roadmap still gets a next step.
+module Plastic
+  class CLI
+    module Commands
+      class Continue < Command
+        USAGE_LINE = "plastic continue [--project SLUG] [--json]"
+
+        def call
+          @output.row("project", scope.slug)
+          @output.row("root", scope.root)
+          @output.row("active", active)
+          @output.row("roadmap", roadmap)
+          command, because = decision
+          @output.next_step(command, because: because)
+        rescue RoadmapSavepoint::MissingGroupingHeading => e
+          raise Failure, e.message
+        end
+
+        private
+
+        def switches(parser)
+          parser.on("--project SLUG") { |slug| @options[:project] = slug }
+        end
+
+        def active
+          scope.active_entries.map { |id, title| "#{id}  #{title}" }
+        end
+
+        def roadmap
+          return Frontier::NONE unless frontier.roadmap
+
+          "#{frontier.roadmap}  frontier #{frontier.heading}"
+        end
+
+        def decision
+          return [frontier.next_step, frontier.because] if frontier.id
+
+          id = scope.active_ids.first
+          return [plan_for(id), "#{id} is the first active intent in #{scope.slug}"] if id
+
+          ["plastic help", "#{scope.slug} has no active work and no roadmap"]
+        end
+
+        def plan_for(id)
+          dir = scope.intent_dir(id)
+          dir ? "read #{File.join(dir, "plan.md")}" : "plastic status"
+        end
+
+        def frontier
+          @frontier ||= Frontier.new(scope)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "installer_verb"
+
+# `plastic doctor` - diagnoses Plastic installation health. The work is still
+# scripts/doctor.rb, run through Legacy; each finding prints its own repair.
+module Plastic
+  class CLI
+    module Commands
+      class Doctor < InstallerVerb
+        USAGE_LINE = "plastic doctor [--core] [--store WHICH]"
+        FLAGS = %w[--core --store].freeze
+
+        SCRIPT = "doctor.rb"
+        AFTER = "none"
+        BECAUSE = "the findings are the whole answer, and each one names its own repair"
+      end
+    end
+  end
+end