@zalom/plastic 2.0.0-alpha.9 → 2.0.2

package/scripts/lib/cli/output.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "json"
+require "shellwords"
+
+# Plastic::CLI::Output (intent 363) - one place where a command's answer is
+# printed. A result is rows of label and value; every command ends with a
+# `next:` line and the `because:` line that gives the rule behind it, which is
+# where the step order the skills used to carry now lives. `--json` prints the
+# same three things with stable keys.
+#
+# Results go to the output stream and diagnostics to the error stream, so a
+# caller can pipe one without the other. Nothing here colours its output.
+module Plastic
+  class CLI
+    class Output
+      LABEL_GAP = 2
+
+      attr_writer :project
+
+      def initialize(out:, err:, json: false)
+        @json = json
+        @raw = []
+        @out = out
+        @err = err
+        @rows = []
+        @next_step = nil
+        @because = nil
+        @flushed = false
+      end
+
+      def row(label, value)
+        @rows << [label, value]
+        self
+      end
+
+      def next_step(command, because:)
+        @next_step = command
+        @because = because
+        self
+      end
+
+      def flush(json: false)
+        return self if @flushed
+
+        @flushed = true
+        json ? print_json : print_text
+        self
+      end
+
+      def document(value)
+        @out.puts JSON.pretty_generate(value)
+        @flushed = true
+        self
+      end
+
+      def raw(text)
+        @json ? @raw << text : @out.puts(text)
+        self
+      end
+
+      def usage(message, banner)
+        @err.puts "plastic: #{message}"
+        @err.puts banner
+        error_document(message, "usage")
+        self
+      end
+
+      def refused(message)
+        @err.puts "plastic: refused, #{message}"
+        @err.puts "This step belongs to the owner. Stop and ask; do not retry with a flag."
+        error_document(message, "refused")
+        self
+      end
+
+      def failed(message)
+        @err.puts "plastic: #{message}"
+        error_document(message, "failed")
+        self
+      end
+
+      private
+
+      def error_document(message, kind)
+        return unless @json
+
+        row("error", {"kind" => kind, "message" => message})
+        next_step("none", because: message)
+        flush(json: true)
+      end
+
+      def result
+        data = @rows.to_h
+        data["output"] = @raw unless @raw.empty?
+        data
+      end
+
+      def scoped_next
+        return @next_step unless @project && @next_step&.match?(/\Aplastic (?:intent|auto|roadmap|continue|next|search)\b/)
+        return @next_step if @next_step.include?("--project")
+
+        "#{@next_step} --project #{Shellwords.escape(@project)}"
+      end
+
+      def print_json
+        @out.puts JSON.pretty_generate("result" => result, "next" => scoped_next,
+          "because" => @because)
+      end
+
+      def print_text
+        printed = print_rows
+        return unless @next_step
+
+        @out.puts if printed
+        @out.puts "next: #{scoped_next}"
+        @out.puts "because: #{@because}"
+      end
+
+      def print_rows
+        width = label_width
+        printed = false
+        @rows.each do |label, value|
+          Array(value).each_with_index do |item, index|
+            @out.puts "#{(index.zero? ? label : "").ljust(width)}#{item}"
+            printed = true
+          end
+        end
+        printed
+      end
+
+      def label_width
+        widths = @rows.reject { |_label, value| Array(value).empty? }.map { |label, _value| label.length }
+        widths.empty? ? 0 : widths.max + LABEL_GAP
+      end
+    end
+  end
+end

package/scripts/lib/cli/scope.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require_relative "../store_layout"
+require_relative "../index_entry"
+require_relative "../store_discovery"
+
+# Plastic::CLI::Scope (intent 363) - which store a command works on. Six skills
+# used to restate this rule in prose; it is stated here once.
+#
+# A named project wins. With no name, the project whose repository holds the
+# working directory wins, longest path first, so a repository nested inside
+# another resolves to the inner one. With neither, the global store answers.
+#
+# Every path comes from the injected environment and home directory, so a test
+# points at a temporary store and never at the real ~/.plastic.
+module Plastic
+  class CLI
+    class Scope
+      UnknownProject = Class.new(StandardError)
+
+      GLOBAL = "global"
+
+      def initialize(env:, home:, slug: nil, directory: Dir.pwd)
+        @env = env
+        @home = home
+        @requested = slug
+        @directory = canonical_path(File.expand_path(directory))
+      end
+
+      def plastic_home
+        @plastic_home ||= @env["PLASTIC_HOME"] || File.join(@home, ".plastic")
+      end
+
+      def stores
+        @stores ||= StoreDiscovery.discover(plastic_home)[:stores]
+      end
+
+      def slug
+        @slug ||= resolve_slug
+      end
+
+      def root
+        @root ||= found&.fetch(:root) || plastic_home
+      end
+
+      def store
+        File.join(root, "store")
+      end
+
+      def index_path
+        File.join(root, "INDEX.md")
+      end
+
+      def roadmaps_dir
+        File.join(root, "roadmaps")
+      end
+
+      def active_entries
+        return [] unless File.exist?(index_path)
+
+        section(File.read(index_path)).filter_map do |line|
+          match = IndexEntry.match(line)
+          match && [match[1], match[2]]
+        end
+      end
+
+      def active_ids
+        active_entries.map(&:first)
+      end
+
+      def intent_dir(id)
+        Dir.glob(File.join(store, "#{id}--*")).min
+      end
+
+      def directory_project
+        @directory_project = project_for_directory unless defined?(@directory_project)
+        @directory_project
+      end
+
+      def known_slugs
+        stores.map { |store| store[:slug] }.sort
+      end
+
+      private
+
+      def found
+        stores.find { |store| store[:slug] == slug }
+      end
+
+      def resolve_slug
+        return requested_slug if @requested
+
+        directory_project || GLOBAL
+      end
+
+      def requested_slug
+        return @requested if known_slugs.include?(@requested)
+
+        raise UnknownProject,
+          "no project named #{@requested.inspect}; this machine has #{known_slugs.join(", ")}"
+      end
+
+      def project_for_directory
+        (repositories + stores.map { |store| [store[:slug], store[:root]] })
+          .select { |_slug, path| inside?(path) }
+          .max_by { |_slug, path| path.length }
+          &.first
+      end
+
+      def inside?(path)
+        path = canonical_path(File.expand_path(path))
+        @directory == path || @directory.start_with?("#{path}#{File::SEPARATOR}")
+      end
+
+      def canonical_path(path)
+        return File.realpath(path) if File.exist?(path)
+
+        File.join(canonical_path(File.dirname(path)), File.basename(path))
+      end
+
+      def repositories
+        StoreProvisioning.load_projects(plastic_home).filter_map do |slug, info|
+          path = info.is_a?(Hash) ? info["path"].to_s : ""
+          [slug, path] unless path.empty?
+        end
+      end
+
+      def section(text)
+        body = text.match(/^##\s+Active\s*$(.*?)(?=^##\s|\z)/m)
+        body ? body[1].lines.map(&:strip) : []
+      end
+    end
+  end
+end

package/scripts/lib/cli/table.rb

@@ -0,0 +1,65 @@
+# 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 migrate" => ["commands/roadmap_migrate", "RoadmapMigrate", "Write a roadmap's Graph section from its batches"],
+      "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

@@ -0,0 +1,198 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+require "timeout"
+require "tmpdir"
+require_relative "runner_policy"
+
+# CodexAdapter (intent 340b, G7c, n6): the argv `codex exec` needs for one
+# node's kind, and the mechanics of running it once - a bounded subprocess
+# whose stdin carries the node input, whose stdout and `--output-last-message`
+# file are the only two places a return can come from, and whose timeout
+# kills the whole process group rather than one pid.
+#
+# Pure where it can be: sandbox_mode, git_dir_for_worktree, add_dir_args and
+# build_argv touch nothing but the filesystem read they are explicitly given
+# (the worktree's own `.git` file), never a git call and never a guess at a
+# repository root. #execute is the one place this module actually spawns a
+# child process; scripts/node-run is the only caller.
+module CodexAdapter
+  module_function
+
+  # Verify and research get NO write access at all (spec D9): read-only, no
+  # `--add-dir`. Everything else - work, and any kind this table has never
+  # heard of - gets the widest treatment, matching RunnerPolicy's own
+  # unknown-kind-falls-back-to-work rule (matrix row 6.10).
+  READ_ONLY_KINDS = %w[verify research].freeze
+
+  def sandbox_mode(kind)
+    READ_ONLY_KINDS.include?(kind.to_s) ? "read-only" : "workspace-write"
+  end
+
+  # The repository's OWN `.git` directory, derived from `worktree`'s `.git`
+  # FILE (a git worktree never carries a real `.git` directory of its own -
+  # spec) rather than any guess at how many path segments separate a
+  # worktree from its repo (matrix row 6.6). `.git` reads
+  # `gitdir: <repo>/.git/worktrees/<name>`; two directories up from that
+  # target is the repository's real `.git`. Returns nil when `worktree` is
+  # not a git worktree at all (no `.git` file, or `.git` is a directory,
+  # meaning `worktree` is a repository's own primary checkout) - callers
+  # treat that as "no `--add-dir` to add", never as a reason to guess.
+  def git_dir_for_worktree(worktree)
+    gitfile = File.join(worktree.to_s, ".git")
+    return nil unless File.file?(gitfile)
+
+    content = File.read(gitfile)
+    m = content.match(/\Agitdir:\s*(.+?)\s*\z/m)
+    return nil unless m
+
+    worktrees_entry = File.expand_path(m[1], worktree.to_s)
+    File.dirname(File.dirname(worktrees_entry))
+  end
+
+  # [] for a read-only kind (matrix row 6.4): `-C` already makes the
+  # worktree writable, and `--add-dir` on top of `--sandbox read-only` would
+  # contradict the sandbox mode itself. Exactly one `--add-dir`, the
+  # repository's own `.git`, for every other kind (matrix row 6.5) - nil
+  # when the worktree's own gitdir pointer cannot be resolved, so a caller
+  # handed a plain (non-worktree) directory never gets a bogus argument.
+  def add_dir_args(kind:, worktree:)
+    return [] if READ_ONLY_KINDS.include?(kind.to_s)
+
+    git_dir = git_dir_for_worktree(worktree)
+    git_dir ? ["--add-dir", git_dir] : []
+  end
+
+  # The whole `codex exec` argv for one node (matrix rows 6.1-6.9): `-C` at
+  # the worktree given (row 6.8), the sandbox mode and `--add-dir` this
+  # kind's row calls for and nothing else (row 6.7 - never the intent
+  # 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:, model: nil, effort: nil)
+    argv = [
+      "codex", "exec",
+      "-C", worktree.to_s,
+      "--sandbox", sandbox_mode(kind),
+      *add_dir_args(kind: kind, worktree: worktree),
+    ]
+    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
+  # length (RunnerPolicy.lease_minutes), never one shared constant - a long
+  # `work` build must not be capped as tightly as a quick `verify` pass.
+  def timeout_seconds(kind)
+    RunnerPolicy.lease_minutes(kind) * 60
+  end
+
+  # The return text (matrix rows 6.18/6.19): `output_last_message_path`'s
+  # own content when it exists and is non-blank (row 6.18 - stdout is never
+  # even inspected on this path), else the last YAML document found in
+  # `stdout` (row 6.19), else nil (no return anywhere - row 6.20 is the
+  # caller's problem, not this method's).
+  def read_return(output_last_message_path:, stdout:)
+    from_file = file_present_content(output_last_message_path)
+    return from_file unless from_file.nil?
+
+    stdout_fallback(stdout)
+  end
+
+  # The LAST YAML document in `text` that parses to a mapping, or nil when
+  # none does (row 6.20's other half). Documents are separated the ordinary
+  # YAML way, a line holding only `---`; a stream with no such separator at
+  # all is treated as one candidate document. Every candidate is tried from
+  # the end, so three documents (one row names explicitly) still resolve to
+  # the last one, and prose or a fragment that never parses to a mapping is
+  # skipped rather than returned as the "document".
+  def stdout_fallback(text)
+    return nil if text.to_s.strip.empty?
+
+    segments = text.to_s.split(/^---[ \t]*$/m).map(&:strip).reject(&:empty?)
+    segments = [text.to_s.strip] if segments.empty?
+
+    segments.reverse_each do |segment|
+      return segment if safe_yaml(segment).is_a?(Hash)
+    end
+    nil
+  end
+
+  # Runs `argv` once, feeding `stdin_data` on stdin through a scratch file
+  # (never a pipe - the same "never deadlock the read side" reasoning
+  # HookReplay.run_bounded already carries), bounded to `timeout_seconds`.
+  # `argv`'s own child becomes its own process group (`pgroup: true`) so a
+  # timeout can kill every child `codex exec` spawned along the way, not
+  # just the pid this call started (matrix row 6.24) - `codex exec` itself
+  # spawns shells for the commands it runs, and those would otherwise
+  # outlive a plain `Process.kill` on the parent alone, holding the
+  # worktree.
+  #
+  # Returns {exit_code:, timed_out:, stdout:, message:}. `message` is
+  # #read_return's result, computed only when the call did not time out - a
+  # timed-out child's partial output is never trusted (matrix row 6.22).
+  def execute(argv, stdin_data:, timeout_seconds:, output_last_message_path:)
+    Dir.mktmpdir("plastic-node-run-") do |scratch|
+      in_path = File.join(scratch, "stdin")
+      out_path = File.join(scratch, "stdout")
+      err_path = File.join(scratch, "stderr")
+      File.binwrite(in_path, stdin_data.to_s)
+
+      pid = Process.spawn(*argv.map(&:to_s), in: in_path, out: out_path, err: err_path, pgroup: true)
+      timed_out = false
+      exit_code =
+        begin
+          Timeout.timeout(timeout_seconds) do
+            Process.wait(pid)
+            $?.exitstatus
+          end
+        rescue Timeout::Error
+          timed_out = true
+          kill_group(pid)
+          nil
+        end
+
+      stdout = File.exist?(out_path) ? File.read(out_path) : ""
+      message = timed_out ? nil : read_return(output_last_message_path: output_last_message_path, stdout: stdout)
+
+      { exit_code: exit_code, timed_out: timed_out, stdout: stdout, message: message }
+    end
+  end
+
+  # --- internals ---------------------------------------------------------------
+
+  def file_present_content(path)
+    return nil if path.nil? || !File.exist?(path)
+
+    content = File.read(path)
+    content.strip.empty? ? nil : content
+  end
+  private_class_method :file_present_content
+
+  def safe_yaml(text)
+    YAML.safe_load(text, aliases: false, permitted_classes: [])
+  rescue Psych::Exception, ArgumentError
+    nil
+  end
+  private_class_method :safe_yaml
+
+  # Kills the whole process GROUP `pid` leads, not just `pid` itself (matrix
+  # row 6.24): a negative pid signals the group. Rescued and reaped exactly
+  # like HookReplay.kill_and_reap - a process that exited in the race
+  # between the timeout firing and this call raises Errno::ESRCH on the kill
+  # or Errno::ECHILD on the wait, neither of which should ever propagate.
+  def kill_group(pid)
+    Process.kill("KILL", -pid)
+  rescue StandardError
+    nil
+  ensure
+    begin
+      Process.wait(pid)
+    rescue StandardError
+      nil
+    end
+  end
+  private_class_method :kill_group
+end

package/scripts/lib/compact_instructions.rb

@@ -19,23 +19,31 @@ require "digest"
 #
 # Library only: no CLI, no ENV, no I/O.
 module CompactInstructions
-  # 35 and 50 percent of a 1M window.
-  OFFER_TOKENS = 350_000
-  INSIST_TOKENS = 500_000
+  # 15 and 25 percent of a 1M window (intent 355, n5, D7).
+  OFFER_TOKENS = 150_000
+  INSIST_TOKENS = 250_000
 
   # Static on purpose. A body rendered from the user's config would change its hash
   # every time they edited config.yml, and doctor would then report a correct install
   # 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:
 
-    - At 350,000 tokens, offer to compact. Say that the hand-off in today's day ledger
+    - At 150,000 tokens, offer to compact. Say that the hand-off in today's day ledger
       is written and current, and take no for an answer: a task that is nearly done
       does not need the interruption.
-    - At 500,000 tokens, insist. Take no new work, write the hand-off in today's day
+    - At 250,000 tokens, insist. Take no new work, write the hand-off in today's day
       ledger, and compact before continuing.
     - After a compaction, say continue. The day summary at boot and the hand-off carry
       the state; do not rebuild it by re-reading files.