@zalom/plastic 1.0.0-beta.9 → 1.0.0

package/scripts/hook-retrieval-gate

@@ -0,0 +1,148 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# PreToolUse retrieval gate (intent 84, Lever 2; operation-based redesign 89a;
+# ADVISORY since intent 108, D8). Reads the tool call (JSON on stdin: tool_name +
+# tool_input), computes capabilities (QMD detect + freshness), and delegates the
+# decision to RetrievalGate. It NEVER blocks: reads and searches always run
+# (exit 0). A store content search that QMD could serve better gets a QMD hint
+# via PreToolUse additionalContext on stdout. Hard gates guard writes, locks,
+# and structure; never reads.
+# Fail-open: any parse error, timeout, or unexpected exception exits 0. On the
+# STALE QMD path RetrievalGate fires QmdSync.reindex_async (NEVER synchronous).
+# Binds subagents (PreToolUse hooks apply to subagent tool calls too).
+#
+# Only CONTENT SEARCH over store markdown gets the hint; reads and structural
+# ops stay silent. Code navigation is a soft prompt recommendation
+# (UserPromptSubmit power-tools), not handled here.
+#
+# Scope: only the agent's own Bash/Read/Grep/Glob calls. Ruby `File.read` inside
+# scripts is invisible to a PreToolUse hook and is out of scope (no exemptions).
+#
+# ARGV[0] is plastic_home (passed by the launcher), like hook-qmd-search.
+
+require "json"
+require "timeout"
+require_relative "lib/retrieval_gate"
+require_relative "lib/qmd_sync"
+
+module RetrievalGateHook
+  module_function
+
+  # Pure-ish core: capabilities and reindex are injected so this is unit-testable
+  # with no real qmd. Returns [exit_code, stderr_string, stdout_json].
+  #   stdin: raw PreToolUse JSON
+  #   capabilities: { qmd:, qmd_fresh: }
+  #   reindex: callable fired on the STALE path
+  def run(stdin:, plastic_home:, cwd:, capabilities:, reindex: -> {})
+    payload = parse(stdin)
+    return [0, nil, nil] unless payload
+
+    tool_name = payload["tool_name"].to_s
+    tool_input = payload["tool_input"]
+    tool_input = {} unless tool_input.is_a?(Hash)
+
+    bypassed = false
+    reason = RetrievalGate.decision(
+      tool_name: tool_name, tool_input: tool_input,
+      plastic_home: plastic_home, cwd: cwd,
+      capabilities: capabilities, reindex: reindex
+    ) { |_sig| bypassed = true }
+
+    if reason
+      # Advisory (intent 108, D8): reads and searches are never denied. The
+      # would-block reason becomes a hint the agent sees alongside the result.
+      hint = JSON.generate(
+        "hookSpecificOutput" => {
+          "hookEventName" => "PreToolUse",
+          "additionalContext" =>
+            "PLASTIC advisory: #{reason} (this search ran; the hint is not a block)"
+        }
+      )
+      [0, nil, hint]
+    else
+      # The `# qmd-ok` bypass token is still accepted (bypassed is set), but
+      # with nothing to bypass it no longer announces itself.
+      [0, nil, nil]
+    end
+  rescue StandardError
+    [0, nil, nil] # fail-open
+  end
+
+  def parse(raw)
+    data = JSON.parse(raw.to_s)
+    data.is_a?(Hash) ? data : nil
+  rescue StandardError
+    nil
+  end
+
+  # Detect real capabilities for the live executable. Probes are injected so the
+  # three-tier QMD failure model is unit-testable:
+  #   - absent  : QMD not on PATH                 -> allow, no warn.
+  #   - broken  : QMD present but freshness probe  -> tier-b: WARN once, then treat
+  #               raises/times out                   as absent this turn (allow).
+  #   - fresh   : probe returns truthy            -> gate is live.
+  # A slow `qmd status` cannot stall a tool call: a 2s Timeout bounds the probe.
+  def detect_capabilities(cwd:,
+                          detect: -> { QmdSync.detect },
+                          fresh: -> { QmdSync.fresh? },
+                          warn: ->(m) { $stderr.puts(m) })
+    qmd = detect.call
+    qmd_fresh = false
+    if qmd
+      begin
+        qmd_fresh = Timeout.timeout(2) { fresh.call }
+      rescue StandardError
+        # Tier-b: QMD is present but its freshness probe broke/stalled. Distinct
+        # from QMD being absent — warn so a degraded QMD is visible, then fail open
+        # (allow this turn, no reindex).
+        warn.call("PLASTIC GATE — QMD is present but its freshness probe failed; " \
+                  "allowing this turn without routing search to QMD (check qmd).")
+        qmd = false
+        qmd_fresh = false
+      end
+    end
+    { qmd: qmd, qmd_fresh: qmd_fresh }
+  end
+
+  # Best-effort reindex callable for the STALE path. Resolves the collection from
+  # cwd (project + global) and fires the async reindexer for each; never raises.
+  def reindex_for(cwd:, plastic_home:)
+    lambda do
+      begin
+        cols = QmdSync.collections_for_cwd(cwd, plastic_home: plastic_home)
+        cols.each { |c| QmdSync.reindex_async(collection: c) }
+      rescue StandardError
+        # non-fatal; the read is already allowed this turn
+      end
+    end
+  end
+end
+
+# --- executable entrypoint ---
+if $PROGRAM_NAME == __FILE__
+  raw = begin
+    $stdin.read
+  rescue StandardError
+    ""
+  end
+
+  plastic_home = (ARGV[0] && !ARGV[0].empty?) ? ARGV[0] : File.expand_path("~/.plastic")
+  cwd = Dir.pwd
+
+  code, err, out = begin
+    caps = RetrievalGateHook.detect_capabilities(cwd: cwd)
+    RetrievalGateHook.run(
+      stdin: raw, plastic_home: plastic_home, cwd: cwd,
+      capabilities: caps,
+      reindex: RetrievalGateHook.reindex_for(cwd: cwd, plastic_home: plastic_home)
+    )
+  rescue StandardError
+    [0, nil, nil] # fail-open at the outermost boundary too
+  end
+
+  $stderr.puts(err) if err && !err.empty?
+  print out if out && !out.empty?
+  exit code
+end

package/scripts/hook-savepoint-pre

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+# Usage: hook-savepoint-pre <file_path>
+#
+# PreToolUse savepoint trigger (intent 81). When a stage-opening lifecycle file
+# (spec.md => Why, plan.md => How) is ABOUT to be written into an intent dir,
+# append the pre-stage `started` ledger line so the ledger records "this stage
+# was entered" before its artifact lands.
+#
+# Like the PostToolUse decoupled savepoint write (intent 52), it is derived from
+# the file path alone: no bridge, no session, fires headless. It NEVER blocks a
+# write: any non-match or failure exits 0. The append is idempotent and only
+# fires while the stage is genuinely starting (the artifact is not yet a real,
+# non-placeholder file), so re-edits add nothing.
+
+require_relative "lib/bridge"
+
+file_path = ARGV[0]
+exit 0 if file_path.nil? || file_path.empty?
+
+file_path_abs = File.expand_path(file_path)
+intent_dir = Bridge.intent_dir_for(file_path_abs)
+exit 0 unless intent_dir
+
+begin
+  Bridge.append_started_savepoint(intent_dir, file_path_abs)
+rescue StandardError
+  # best-effort; the ledger is rebuildable and the post line still lands
+end
+
+exit 0

package/scripts/hook-session-start

@@ -48,7 +48,7 @@ bridge_data = nil
 if active.length == 1 && active.first =~ /store\/([\w-]+)\//
   dir_name = $1
   intent_dir = "#{store_root}/store/#{dir_name}"
-  session = ENV["CLAUDE_SESSION_ID"] || Process.pid.to_s
+  session = ENV["CLAUDE_CODE_SESSION_ID"] || Process.pid.to_s
   intent_id = dir_name.split("--").first
   intent_name = active.first[/\[([^\]]+)\]/, 1] || "unknown"
   bridge_data = Bridge.derive(session, intent_id: intent_id, intent_dir: intent_dir, store: store_root, name: intent_name)

package/scripts/insight-append

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# insight-append - the blessed write path for an intent's `## Insights` section
+# (intent 82). A thin CLI wrapper over Insights.append_insight: it formats the
+# `{utc-iso8601} · {stage} · {author}` prefix, validates it, and appends one
+# entry at the bottom of the section (creating the section or file if absent).
+#
+# Sibling to scripts/spawn-preamble and scripts/agent-report. The library's
+# `now:` seam is the test seam; the CLI uses the default Time.now, which is fine
+# because determinism is covered at the library level (test/insights_test.rb).
+#
+# Usage:
+#   insight-append <intent_dir> <text> --stage S --author A
+#
+# Exit codes: 0 (entry appended), 2 (usage).
+
+require_relative "lib/insights"
+
+def parse_args(argv)
+  stage = nil
+  author = nil
+  positional = []
+  i = 0
+  while i < argv.length
+    case argv[i]
+    when "--stage"
+      stage = argv[i + 1]
+      i += 2
+    when "--author"
+      author = argv[i + 1]
+      i += 2
+    else
+      positional << argv[i]
+      i += 1
+    end
+  end
+  [positional[0], positional[1], stage, author]
+end
+
+intent_dir, text, stage, author = parse_args(ARGV)
+
+if [intent_dir, text, stage, author].any? { |v| v.nil? || v.to_s.empty? }
+  warn "usage: insight-append <intent_dir> <text> --stage S --author A"
+  exit 2
+end
+
+entry = Insights.append_insight(File.expand_path(intent_dir), text,
+                                stage: stage, author: author)
+puts "appended: #{entry}"

package/scripts/install.rb

@@ -14,6 +14,7 @@
 # so install.rb is the single file-syncer; the ledger action is contextual.
 
 require_relative "lib/installer_core"
+require_relative "lib/preflight"
 
 class Install < InstallerCore
   def cli(argv = ARGV)
@@ -22,6 +23,9 @@ class Install < InstallerCore
       return 0
     end
 
+    gate = preflight_gate
+    return gate unless gate.zero?
+
     force = argv.include?("--force")
     reinstall = argv.include?("--reinstall")
     ledger_action = flag_value(argv, "--ledger-action")
@@ -42,19 +46,19 @@ class Install < InstallerCore
       return 1
     end
 
-    run(selected: selected, force: force, reinstall: reinstall, ledger_action: ledger_action)
+    run(selected: selected, force: force, reinstall: reinstall, ledger_action: ledger_action, argv: argv)
     0
   end
 
   # Hermetic entrypoint (no prompting / no exit). Returns the per-agent results array.
-  def run(selected:, force: false, reinstall: false, ledger_action: nil)
+  def run(selected:, force: false, reinstall: false, ledger_action: nil, argv: ARGV, input: $stdin)
     fresh = !installed?
     mode = fresh ? :install : :update # :update here means "re-sync, skip bootstrap"
 
     distribute(mode)
     bootstrap if fresh
 
-    results = selected.map { |key| install_for_agent(key, force) }
+    results = selected.map { |key| install_for_agent(key, force, argv: argv, input: input, reinstall: reinstall) }
 
     action = ledger_action || (fresh ? "install" : "reinstall")
     ledger_append(version, action)
@@ -72,8 +76,37 @@ class Install < InstallerCore
     File.exist?(path) ? File.read(path).strip : nil
   end
 
+  # Injectable pre-flight gate: real probes as default args, printing to an
+  # injectable `out:` IO so this is hermetically testable via StringIO. Returns
+  # 1 (stop the install) when Ruby is missing/too-old, else 0.
+  def preflight_gate(ruby_version: RUBY_VERSION, node_version: node_probe, git_present: git_probe,
+                      mise_present: mise_probe, out: $stderr)
+    result = Preflight.check(ruby_version: ruby_version, node_version: node_version,
+                              git_present: git_present, mise_present: mise_present)
+    result[:messages].each { |message| out.puts(message) }
+    result[:fatal] ? 1 : 0
+  end
+
   private
 
+  def node_probe
+    `node --version`.strip
+  rescue StandardError
+    ""
+  end
+
+  def git_probe
+    !`command -v git`.strip.empty?
+  rescue StandardError
+    false
+  end
+
+  def mise_probe
+    !`command -v mise`.strip.empty?
+  rescue StandardError
+    false
+  end
+
   def flag_value(argv, name)
     i = argv.index(name)
     return nil unless i && argv[i + 1]
@@ -96,7 +129,8 @@ class Install < InstallerCore
     verb = mode == :reinstall ? "re-synced" : "installed"
     puts "\n\u{2705} Plastic v#{version} #{verb}."
     puts "   Registered for: #{installed.map { |r| r[:agent] }.join(", ")}"
-    puts "   Run /clear (or restart your agent) to pick up new conventions.\n\n"
+    puts "   Run /clear (or restart your agent) to pick up new conventions."
+    puts "   Next: read docs/guides/your-first-intent-in-10-minutes.md\n\n"
   end
 
   def show_help
@@ -119,9 +153,12 @@ class Install < InstallerCore
         --alpha       Alpha channel
 
       Other options:
-        --reinstall   Re-sync core files for the installed version (repair). Store untouched.
-        --force       Overwrite existing files without prompting
-        -h, --help    Show this help
+        --reinstall          Re-sync core files for the installed version (repair). Store untouched.
+        --force              Overwrite existing files without prompting
+        --statusline VALUE   keep or plastic. If an existing statusline is found, this
+                             skips the interactive prompt. Interactive sessions ask by
+                             default; non-interactive sessions default to keep.
+        -h, --help           Show this help
 
       Notes:
         Install is one-shot. If Plastic is already installed, use `update` to upgrade or

package/scripts/lib/agent_models.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Shared model-tier resolution for Plastic subagents (intent 116).
+#
+# TIER_DEFAULTS mirrors the shipped `agents/*.md` frontmatter so `read-config`
+# can answer `agents.models.<basename>` with the built-in default. The installer
+# does NOT use TIER_DEFAULTS: it applies only genuine config overrides via
+# `override_map`, so shipped frontmatter with no override passes through
+# unchanged.
+module AgentModels
+  # Claude Code aliases only (never pinned ids, never Fable). Keys are the agent
+  # file basenames without the `.md` extension.
+  TIER_DEFAULTS = {
+    "plastic-enforcer" => "opus",
+    "plastic-brainstorming" => "opus",
+    "plastic-planner" => "opus",
+    "plastic-spec-specialist" => "sonnet",
+    "plastic-executor" => "sonnet",
+    "plastic-intent-curator" => "sonnet",
+    "plastic-future-intent-researcher" => "sonnet",
+    "plastic-intent-discovery" => "sonnet"
+  }.freeze
+
+  module_function
+
+  # Pull the `agents.models` sub-hash out of a loaded config hash, tolerating a
+  # missing or malformed shape. Returns a plain { basename => model } hash.
+  def models_section(config)
+    return {} unless config.is_a?(Hash)
+    agents = config["agents"]
+    return {} unless agents.is_a?(Hash)
+    section = agents["models"]
+    section.is_a?(Hash) ? section : {}
+  end
+
+  # Override map for the installer: global overrides overlaid by project
+  # overrides (project wins). Defaults are intentionally excluded. Unknown agent
+  # keys are carried through as-is; install_agents simply never matches them to a
+  # copied file, so they are ignored without raising.
+  def override_map(project_config: {}, global_config: {})
+    models_section(global_config).merge(models_section(project_config))
+  end
+end