@zalom/plastic 1.0.0-beta.2 → 1.0.0-beta.21

package/scripts/lib/power_tools.rb

@@ -0,0 +1,76 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "qmd_sync"
+
+# PowerTools — detect-then-degrade harness for Plastic's optional power-tools
+# (intent 66b). It owns deterministic detection of each tool and builds an
+# obligation ("mandate") string for whichever tools are present, so the agent is
+# obliged (not merely reminded) to use them: QMD for finding intents, Serena for
+# code navigation.
+#
+# Strictly detect-then-degrade: a tool that is absent contributes nothing, and
+# `mandate` returns nil when no tool is present. Nothing here installs anything.
+#
+# Pure and dependency-injected: every detection runs through an injected callable
+# or keyword probe (PATH scan / `.serena` marker walk), so the whole module is
+# unit-testable with no real binaries, no network, and no global/ENV state.
+module PowerTools
+  module_function
+
+  # True when QMD is present. Reuses QmdSync.detect (PATH probe), injectable.
+  def qmd?(detector: QmdSync.method(:detect))
+    !!detector.call
+  end
+
+  # True when Serena is present: a `.serena` directory exists in cwd or any
+  # ancestor, OR `serena` is resolvable on PATH. Both probes are injectable so
+  # tests do not depend on the host having Serena installed.
+  def serena?(cwd:, path_probe: method(:which_serena), marker_finder: method(:serena_marker?))
+    return true if marker_finder.call(cwd)
+    !!path_probe.call
+  end
+
+  # True when `serena` is an executable on PATH. Mirrors QmdSync.which_qmd.
+  def which_serena
+    ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
+      candidate = File.join(dir, "serena")
+      File.file?(candidate) && File.executable?(candidate)
+    end
+  end
+
+  # Walk up from cwd to the filesystem root, returning true if any level holds a
+  # `.serena` directory.
+  def serena_marker?(cwd)
+    dir = File.expand_path(cwd)
+    loop do
+      return true if Dir.exist?(File.join(dir, ".serena"))
+      parent = File.dirname(dir)
+      break if parent == dir
+      dir = parent
+    end
+    false
+  end
+
+  # Obligation text for whichever tools are present, joined by newlines, or nil
+  # when none are. One MANDATORY line per present tool.
+  def mandate(cwd:, qmd_detector: QmdSync.method(:detect), serena_detector: nil)
+    lines = []
+
+    if qmd?(detector: qmd_detector)
+      lines << "MANDATORY: you MUST use QMD (`qmd search` / `qmd query` over the " \
+               "`plastic-*` collections) to check for an existing or related intent " \
+               "before treating this as new work; do not grep/Read the store first."
+    end
+
+    serena_present = serena_detector ? !!serena_detector.call : serena?(cwd: cwd)
+    if serena_present
+      lines << "MANDATORY: you MUST use Serena's symbolic tools (find_symbol / " \
+               "get_symbols_overview / find_referencing_symbols) for code navigation " \
+               "before grep/Read."
+    end
+
+    return nil if lines.empty?
+    lines.join("\n")
+  end
+end

package/scripts/lib/qmd_hook.rb

@@ -2,43 +2,56 @@
 # frozen_string_literal: true
 
 require_relative "qmd_sync"
+require_relative "power_tools"
 
-# QmdHook — decision logic for the qmd-first UserPromptSubmit hook (intent 66).
-# Pure and dependency-injected: returns the additionalContext string to emit, or
-# nil to emit nothing. The executable hook wires real deps and prints; this is
-# unit-tested with a fake runner/detector (no real qmd, no network).
+# QmdHook — decision logic for the power-tools UserPromptSubmit hook (intents 66,
+# 66b). Pure and dependency-injected: returns the additionalContext string to
+# emit, or nil to emit nothing. The executable hook wires real deps and prints;
+# this is unit-tested with a fake runner/detector (no real qmd, no network).
+#
+# When qmd is present it still injects scored qmd hits (intent 66), then appends
+# the PowerTools mandate (a MUST obligation per present tool: qmd for finding
+# intents, serena for code navigation) instead of the old soft reminder.
 module QmdHook
   module_function
 
   MIN_PROMPT_LENGTH = 10
-  REMINDER = "qmd is available: query it (`qmd search` / `qmd query` over the " \
-             "`plastic-*` collections) before grep/Read when gathering intent " \
-             "context (sources/chain) or checking whether this work already " \
-             "exists as an intent."
 
   def run(prompt:, cwd:, plastic_home:, runner: QmdSync.default_runner,
-          detector: QmdSync.method(:detect), limit: 3, min_score: 0.5)
-    return nil unless detector.call
-    p = prompt.to_s.strip
-    return nil if p.length < MIN_PROMPT_LENGTH
-    return nil if p.downcase == "continue"
+          detector: QmdSync.method(:detect), limit: 3, min_score: 0.5,
+          serena_detector: nil)
+    serena_detector ||= -> { PowerTools.serena?(cwd: cwd) }
+    qmd_present = !!detector.call
+    serena_present = !!serena_detector.call
+    return nil unless qmd_present || serena_present
 
-    collections = QmdSync.collections_for_cwd(cwd, plastic_home: plastic_home)
-    hits = QmdSync.search(p, collections: collections, limit: limit,
-                          min_score: min_score, runner: runner, detector: detector)
+    p = prompt.to_s.strip
+    # The hit SEARCH is the only expensive step and the only one gated by prompt
+    # triviality: skip it for short or bare-"continue" prompts (and when qmd is
+    # absent). The mandate itself is always-on for whichever tools are present.
+    search_ok = qmd_present && p.length >= MIN_PROMPT_LENGTH && p.downcase != "continue"
 
     parts = []
-    if hits.any?
-      parts << "Related / prior Plastic intents (qmd BM25, includes completed) — " \
-               "check before treating this as new work:"
-      hits.each do |h|
-        loc = h[:file].to_s.sub(%r{\Aqmd://}, "")
-        pct = (h[:score] * 100).round
-        parts << "- [#{pct}%] #{loc} — #{h[:title]}"
+    if search_ok
+      collections = QmdSync.collections_for_cwd(cwd, plastic_home: plastic_home)
+      hits = QmdSync.search(p, collections: collections, limit: limit,
+                            min_score: min_score, runner: runner, detector: detector)
+      if hits.any?
+        parts << "Related / prior Plastic intents (qmd BM25, includes completed) — " \
+                 "check before treating this as new work:"
+        hits.each do |h|
+          loc = h[:file].to_s.sub(%r{\Aqmd://}, "")
+          pct = (h[:score] * 100).round
+          parts << "- [#{pct}%] #{loc} — #{h[:title]}"
+        end
+        parts << ""
       end
-      parts << ""
     end
-    parts << REMINDER
+
+    mandate = PowerTools.mandate(cwd: cwd, qmd_detector: -> { qmd_present },
+                                 serena_detector: -> { serena_present })
+    parts << mandate if mandate
+    return nil if parts.empty?
     parts.join("\n")
   end
 end

package/scripts/lib/qmd_sync.rb

@@ -99,6 +99,42 @@ module QmdSync
     { ran: true, ok: (ok1 && ok2) }
   end
 
+  # Non-blocking reindex for the completion path. QMD has no incremental reindex
+  # (`qmd update` is a full rescan, `qmd embed -c` re-embeds the whole collection,
+  # ~2 min), so running it inline would block the agent's turn; spawning detached
+  # returns immediately. No-op when qmd absent. Spawner/detector are injected so
+  # tests assert behavior with no real qmd and no real spawned process.
+  def reindex_async(collection:, detector: method(:detect), spawner: method(:default_async_spawner))
+    return skip_result unless detector.call
+    pid = spawner.call(collection)
+    { ran: true, async: true, pid: pid }
+  end
+
+  # Default spawner: launch `qmd update && qmd embed -c <collection>` detached and
+  # non-blocking, discarding output, then detach so it never blocks the turn.
+  def default_async_spawner(collection)
+    require "shellwords"
+    cmd = "qmd update && qmd embed -c #{Shellwords.escape(collection)}"
+    pid = Process.spawn(cmd, out: File::NULL, err: File::NULL, pgroup: true)
+    Process.detach(pid)
+    pid
+  end
+
+  # True when the QMD index has no pending (unembedded) documents. Binary
+  # freshness signal for the retrieval gate (intent 84, Lever 2). `qmd status` is
+  # plain text (no --json); it prints a line like "Pending: N need embedding".
+  # No pending line found -> treat as fresh (conservative: a parse miss must not
+  # block reads). Runner failure -> false (cannot confirm freshness). The caller
+  # gates on `detect` first, so absence is handled upstream; this only answers
+  # "is the present index fresh?". Pure via the injected runner.
+  def self.fresh?(runner: default_runner)
+    out, ok = runner.call(["status"])
+    return false unless ok && out
+    m = out[/^\s*Pending:\s*(\d+)\b/i, 1]
+    pending = m ? m.to_i : 0
+    pending.zero?
+  end
+
   # Read-only status used by doctor and the session-start report line.
   # Returns a structured hash; never mutates the index.
   def status(plastic_home:, runner: default_runner, detector: method(:detect))

package/scripts/lib/retrieval_gate.rb

@@ -0,0 +1,211 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "bridge"
+
+# RetrievalGate — the single, pure decision for Lever 2 of intent 84, redesigned
+# operation-based in intent 89a.
+#
+# Given an agent tool call (Bash/Read/Grep/Glob) and injected capability signals,
+# it decides whether to BLOCK the call (returning a redirect-to-QMD reason String)
+# or ALLOW it (returning nil). All capability/freshness signals are injected by the
+# caller (the hook); this module shells out to nothing, reads no globals, and runs
+# no binaries. Mirrors bridge.rb's decision-fn convention (reason String to block,
+# nil to allow).
+#
+# Operation-based policy (intent 89, ## Redesign):
+#   - The gate distinguishes DISCOVERY (content search) from READING a known target.
+#   - Only CONTENT SEARCH over store markdown is hard-gated -> QMD.
+#   - Reading a known target (Read, cat/head/tail) and structural discovery (Glob,
+#     find, ls) are ALWAYS allowed, including over the store.
+#   - Code navigation is a soft prompt MANDATE (PowerTools / UserPromptSubmit), not a
+#     hard gate here. Content grep over code is allowed (Serena cannot grep strings).
+#
+# Content-search vectors (the only ones that can be gated):
+#   - the Grep tool (its `path` search root)
+#   - bash `grep`/`rg`/`ag` (their path args; the first bareword is the PATTERN)
+#
+# QMD enforcement is BINARY (no advisory tier):
+#   - store-md content search: QMD detected+fresh -> BLOCK; detected+stale -> fire
+#     reindex, ALLOW this turn; absent/broken -> ALLOW (the hook warns on broken).
+#
+# Bypass: a TRAILING `# qmd-ok` shell comment on a Bash command (not a substring; a
+# quoted/echoed occurrence does not bypass). It is the auditable seam for "I tried
+# discovery and it did not serve me" (empty, low, or wrongly-scored results).
+#
+# Scope: only the agent's own tool calls. Ruby `File.read` inside scripts is invisible
+# to a PreToolUse hook and is explicitly out of scope (no exemptions).
+module RetrievalGate
+  module_function
+
+  # A `# qmd-ok` token that is a real TRAILING shell comment, after stripping a
+  # trailing newline. The token must be preceded by whitespace (or start the
+  # command) and run to end-of-string. `echo "# qmd-ok"` does NOT match: the token
+  # there is followed by a closing quote, not end-of-string.
+  BYPASS_RE = /(?:\A|\s)#\s*qmd-ok\s*\z/.freeze
+
+  # Bash utilities that perform CONTENT SEARCH (scan file CONTENT for a pattern).
+  # These are the only bash read-vectors that can be gated; readers (cat/head/tail)
+  # and structural tools (find/ls) are never gated.
+  CONTENT_SEARCH_UTILS = %w[grep rg ag].freeze
+
+  # Decide. Returns nil to ALLOW, or a reason String to BLOCK.
+  #   capabilities: { qmd:, qmd_fresh: } (booleans).
+  #   reindex: no-arg callable fired once when a QMD-class target is STALE.
+  # When bypassed, returns nil and (if given) yields :bypass to the optional block
+  # so the caller can log it.
+  def decision(tool_name:, tool_input:, plastic_home:, cwd:,
+               capabilities:, reindex: -> {})
+    targets = extract_targets(tool_name, tool_input, cwd: cwd)
+    return nil if targets.empty?
+
+    if bypass?(tool_name, tool_input)
+      yield(:bypass) if block_given?
+      return nil
+    end
+
+    stale_seen = false
+    targets.each do |path|
+      next unless classify(path, plastic_home: plastic_home) == :qmd
+
+      if capabilities[:qmd] && capabilities[:qmd_fresh]
+        return qmd_reason(path)
+      elsif capabilities[:qmd] # present but stale
+        stale_seen = true
+      end
+      # absent/broken -> allow this target
+    end
+
+    reindex.call if stale_seen
+    nil
+  end
+
+  # --- classification ---
+
+  # Operation-based: the store tree is the only gated class (content search whose
+  # target is at/under a store routes to QMD). Everything else is allowed.
+  def classify(path, plastic_home:)
+    return :allow if path.nil? || path.empty?
+    store_path?(path, plastic_home: plastic_home) ? :qmd : :allow
+  end
+
+  # A path AT or UNDER the global store or a project store. We gate the whole store
+  # tree (not just `*.md`) because a content search root is usually a directory:
+  # grepping the store scans its markdown, which is exactly what QMD should serve.
+  def store_path?(path, plastic_home:)
+    abs = absolutize(path)
+    home = File.expand_path(plastic_home)
+    global = File.join(home, "store")
+    return true if abs == global || abs.start_with?("#{global}/")
+
+    projects = File.join(home, "projects")
+    return false unless abs.start_with?("#{projects}/")
+    tail = abs[(projects.length + 1)..].to_s.split(File::SEPARATOR)
+    tail.length >= 2 && tail[1] == "store"
+  end
+
+  def absolutize(path)
+    File.absolute_path?(path) ? path : File.expand_path(path)
+  end
+
+  # --- bypass ---
+
+  # Only Bash commands carry a trailing `# qmd-ok` comment. The token must be a real
+  # trailing comment (BYPASS_RE), so a quoted/echoed occurrence does not bypass.
+  def bypass?(tool_name, tool_input)
+    return false unless tool_name.to_s == "Bash"
+    cmd = tool_input.is_a?(Hash) ? tool_input["command"].to_s : ""
+    BYPASS_RE.match?(cmd.chomp)
+  end
+
+  # --- target extraction ---
+
+  # Paths a CONTENT-SEARCH operation scans. Reads (Read, cat/head/tail) and
+  # structural discovery (Glob, find, ls) are NOT content search -> no targets ->
+  # always allowed. Only the Grep tool and bash grep/rg/ag can be gated. Read
+  # vectors only (this is a READ gate); write vectors are bridge.rb's job.
+  def extract_targets(tool_name, tool_input, cwd:)
+    input = tool_input.is_a?(Hash) ? tool_input : {}
+    case tool_name.to_s
+    when "Grep"
+      # The search root is the target; the query text is not a path.
+      [input["path"]].compact.reject { |s| s.to_s.empty? }
+    when "Bash"
+      bash_search_targets(input["command"].to_s)
+    else
+      # Read, Glob, and every other tool: read / structural op -> never gated.
+      []
+    end
+  end
+
+  # CONTENT-SEARCH path args across a compound command. Conservative: missing an
+  # exotic form is fine; never flag /dev/null or pure pipes.
+  def bash_search_targets(command)
+    return [] unless command.is_a?(String) && !command.empty?
+    targets = []
+    command.split(/[;\n]|&&|\|\||\|/).each do |segment|
+      targets.concat(segment_search_targets(segment))
+    end
+    targets.reject { |t| t.nil? || t.empty? || dev_path?(t) }.uniq
+  end
+
+  def segment_search_targets(segment)
+    tokens = tokenize(segment)
+    return [] if tokens.empty?
+
+    # Skip leading env-style assignments (FOO=bar cmd ...).
+    idx = 0
+    idx += 1 while tokens[idx] && tokens[idx].include?("=") && tokens[idx] !~ /\A-/
+    util = File.basename(tokens[idx].to_s)
+    return [] unless CONTENT_SEARCH_UTILS.include?(util)
+
+    args = tokens[(idx + 1)..] || []
+    path_args_for(args)
+  end
+
+  # Collect path-shaped arguments for a content-search util. Flags are skipped; the
+  # first non-flag bareword is the PATTERN, not a path.
+  def path_args_for(args)
+    paths = []
+    pattern_consumed = false
+    args.each do |a|
+      next if a.start_with?("-")
+      unless pattern_consumed
+        pattern_consumed = true
+        next
+      end
+      paths << a
+    end
+    paths
+  end
+
+  # Minimal tokenizer: split on whitespace, strip surrounding matching quotes off
+  # each token. Good enough for the conservative read-vector parse.
+  def tokenize(segment)
+    segment.to_s.strip.split(/\s+/).map { |t| strip_quotes(t) }
+  end
+
+  def strip_quotes(token)
+    if (token.start_with?('"') && token.end_with?('"')) ||
+       (token.start_with?("'") && token.end_with?("'"))
+      token[1..-2].to_s
+    else
+      token
+    end
+  end
+
+  def dev_path?(path)
+    path == "/dev/null" || path.start_with?("/dev/")
+  end
+
+  # --- reasons ---
+
+  def qmd_reason(path)
+    "retrieval gate: search the store via QMD, not a raw content scan. Reading a " \
+      "known file and listing/globbing the store are fine; only CONTENT SEARCH over " \
+      "store markdown routes through QMD. Use `qmd search`/`qmd query` over the " \
+      "`plastic-*` collections (or `scripts/qmd-sync search`) instead of scanning " \
+      "#{path}. If QMD's results do not answer your need (your reading of the " \
+      "snippets, not their score), append a trailing `# qmd-ok` to a Bash command."
+  end
+end