@zalom/plastic 1.0.0-beta.11 → 1.0.0-beta.13

package/scripts/lib/bridge.rb

@@ -6,6 +6,8 @@ require "yaml"
 require "fileutils"
 require "tempfile"
 require "digest"
+require "socket"
+require_relative "worktree"
 
 module Bridge
   STAGES = %w[what why how exec done].freeze
@@ -272,6 +274,51 @@ module Bridge
     end
   end
 
+  # --- Gate-boundary narration (intent 84, Lever 1) -------------------------
+  #
+  # ONE concise sentence that states what happened AND what's next, preserving
+  # the `Next: ...` hint the agent consumes. Pure and side-effect-free so the
+  # hook stays a thin caller and the formatter is unit-testable in isolation.
+  # No "Stage transition: X -> Y" prose, no arrow; a colon/parentheses carry the
+  # stage word. Returns a single line (no embedded newlines).
+  STAGE_LABELS = {
+    "what" => "What", "why" => "Why", "how" => "How",
+    "exec" => "Exec", "done" => "Done"
+  }.freeze
+
+  NEXT_HINTS = {
+    "why" => "write spec.md",
+    "how" => "Why complete. Invoke plastic-auto to deliver autonomously, or write plan.md manually.",
+    "exec" => "How complete. Invoke plastic-auto or plastic-executing-plan to execute, or work through the checklist manually.",
+    "done" => "Exec complete. Intent must be completed now — write outcome.md, update INDEX.md, auto-commit. Use plastic-auto or do it manually."
+  }.freeze
+
+  def self.stage_label(stage)
+    STAGE_LABELS[stage] || stage.to_s
+  end
+
+  # Build the gate-hook `additionalContext` sentence.
+  #   transition:      "PLASTIC: How reached (plan.md written). Next: <hint>"
+  #   same-stage write: "PLASTIC: plan.md written (How). Next: <hint>"
+  # `new_missing` (missing files for the new stage) takes precedence over the
+  # stage hint, exactly as before, so the `Next:` content is unchanged.
+  def self.gate_narration(old_stage:, new_stage:, basename:, new_missing:, next_hints: NEXT_HINTS)
+    head = if old_stage != new_stage
+             "PLASTIC: #{stage_label(new_stage)} reached (#{basename} written)."
+           else
+             "PLASTIC: #{basename} written (#{stage_label(new_stage)})."
+           end
+
+    nxt =
+      if Array(new_missing).any?
+        "Next: #{Array(new_missing).join(", ")}"
+      elsif next_hints[new_stage]
+        "Next: #{next_hints[new_stage]}"
+      end
+
+    nxt ? "#{head} #{nxt}" : head
+  end
+
   # --- Cycle-step savepoint ledger (intent 34) ------------------------------
   #
   # savepoint.md is a deterministic, append-only, one-line-per-milestone ledger
@@ -304,8 +351,31 @@ module Bridge
     end.compact
   end
 
-  # Append a milestone line for file_path if (and only if) it is a milestone
-  # not already recorded. Returns true when a line was written, false otherwise.
+  # (stage, milestone) pairs already recorded in the ledger. The pair (not the
+  # milestone text alone) is the dedup key, because state-from-ledger lines like
+  # `Why  started` and `How  started` share the milestone text "started" while
+  # being distinct events (intent 81).
+  def self.savepoint_recorded_pairs(intent_dir)
+    f = File.join(intent_dir, SAVEPOINT_FILE)
+    return [] unless File.exist?(f)
+    File.read(f).each_line.filter_map do |line|
+      parts = line.strip.split(/\s{2,}/)
+      parts.length >= 3 ? [parts[1], parts[2]] : nil
+    end
+  end
+
+  # Append one ledger line for (stage, milestone) unless that pair is already
+  # recorded. The single append primitive shared by every line class. Returns
+  # true when a line was written, false when it was a no-op.
+  def self.append_savepoint_line(intent_dir, stage, milestone, now)
+    return false if savepoint_recorded_pairs(intent_dir).include?([stage, milestone])
+    line = "#{now.utc.iso8601}  #{stage}  #{milestone}\n"
+    File.open(File.join(intent_dir, SAVEPOINT_FILE), "a") { |io| io.write(line) }
+    true
+  end
+
+  # Append the artifact-landing milestone for file_path if (and only if) it is a
+  # milestone not already recorded. Returns true when a line was written.
   def self.append_savepoint(intent_dir, file_path, now: Time.now)
     basename = File.basename(file_path)
     stage, milestone = savepoint_milestone(intent_dir, basename)
@@ -313,11 +383,62 @@ module Bridge
     # A sentinel-marked lifecycle file logs NO milestone (the stage is not real
     # yet). The intent file is never sentineled, so it still logs its What line.
     return false unless stage_file_present?(File.join(intent_dir, basename))
-    return false if savepoint_recorded_milestones(intent_dir).include?(milestone)
 
-    line = "#{now.utc.iso8601}  #{stage}  #{milestone}\n"
-    File.open(File.join(intent_dir, SAVEPOINT_FILE), "a") { |io| io.write(line) }
-    true
+    append_savepoint_line(intent_dir, stage, milestone, now)
+  end
+
+  # --- State-from-ledger: pre-stage, exec-start, and terminal lines (81) ------
+  #
+  # On top of intent 34's artifact-landing milestones, the ledger gains:
+  #   - `started` lines, one per cycle stage entry (pre-stage, written by the
+  #     PreToolUse savepoint hook the moment a stage's artifact is first written);
+  #   - an `Exec  started` companion emitted when checklist.md lands;
+  #   - a terminal `Done  delivered|abandoned` line written by the completion path.
+  # None of these are derivable from files on disk, so they are deliberately NOT
+  # part of savepoint_milestone and are never regenerated by rebuild_savepoint:
+  # a rebuilt ledger is the file-landing skeleton, the live ledger is richer.
+
+  # Map a written filename to the [stage, "started"] pre-stage milestone, or nil.
+  # spec.md => entering Why, plan.md => entering How. checklist.md/outcome.md do
+  # not open a stage (checklist's Exec-start is the append_exec_started companion).
+  def self.savepoint_started_milestone(basename)
+    case basename
+    when "spec.md" then ["Why", "started"]
+    when "plan.md" then ["How", "started"]
+    end
+  end
+
+  # Append the pre-stage `started` line for file_path, iff: the basename opens a
+  # stage, the stage is genuinely starting (its artifact is not yet a REAL file,
+  # so a sentinel placeholder still counts as "starting"), and the pair is not
+  # already recorded. Returns true when a line was written.
+  def self.append_started_savepoint(intent_dir, file_path, now: Time.now)
+    basename = File.basename(file_path)
+    stage, milestone = savepoint_started_milestone(basename)
+    return false unless milestone
+    return false if stage_file_present?(File.join(intent_dir, basename))
+
+    append_savepoint_line(intent_dir, stage, milestone, now)
+  end
+
+  # Append the `Exec  started` companion (emitted when checklist.md lands, in the
+  # same PostToolUse event as the `How  checklist.md created` line). Idempotent.
+  def self.append_exec_started(intent_dir, now: Time.now)
+    append_savepoint_line(intent_dir, "Exec", "started", now)
+  end
+
+  TERMINAL_DISPOSITIONS = %w[delivered abandoned].freeze
+
+  # Append the terminal bookend `Done  delivered|abandoned`, written by the
+  # completion path when an intent transfers to INDEX's Completed/Abandoned
+  # section. Idempotent per disposition. Raises on an unknown disposition.
+  def self.append_terminal_savepoint(intent_dir, disposition, now: Time.now)
+    unless TERMINAL_DISPOSITIONS.include?(disposition)
+      raise ArgumentError,
+            "disposition must be one of #{TERMINAL_DISPOSITIONS.join(', ')}, got #{disposition.inspect}"
+    end
+
+    append_savepoint_line(intent_dir, "Done", disposition, now)
   end
 
   # Reconstruct the ledger from files on disk (timestamps from mtimes), in
@@ -368,6 +489,23 @@ module Bridge
         "context_pct" => 0,
         "warning_at" => 80,
         "critical_at" => 90
+      },
+      # Worktree isolation block (intent 73c). Born unprovisioned; arm_auto calls
+      # Worktree.provision to fill it. code/store are abs paths or null.
+      "worktree" => {
+        "code" => nil,
+        "code_branch" => nil,
+        "store" => nil,
+        "store_branch" => nil,
+        "provisioned" => false
+      },
+      # Delivery lock block (intent 73c). The bridge IS the lock; the owner is
+      # whoever armed it. Born unowned; arm_auto stamps owner_session/pid/etc.
+      "lock" => {
+        "owner_session" => nil,
+        "pid" => nil,
+        "acquired_at" => nil,
+        "host" => nil
       }
     }
 
@@ -439,6 +577,25 @@ module Bridge
     end
     data = derive(key, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name)
     data["build"]["auto"] = true
+
+    # Acquire the delivery lock: this armed bridge is now the single owner of the
+    # intent's delivery (intent 73c). Stamp owner + pid liveness fields.
+    data["lock"] = {
+      "owner_session" => key,
+      "pid" => Process.pid,
+      "acquired_at" => Time.now.utc.iso8601,
+      "host" => (Socket.gethostname rescue nil)
+    }
+
+    # Provision the per-intent worktrees (mandatory code worktree for project
+    # intents; fail-open for non-git / global-only). Never let a provision error
+    # break arming: the lock and auto flag still matter.
+    begin
+      Worktree.provision(data)
+    rescue => e
+      $stderr.puts "plastic: worktree provision raised, continuing unprovisioned: #{e.message}"
+    end
+
     write(key, data)
     purge_done_bridges(session: key)
     data
@@ -450,6 +607,16 @@ module Bridge
     return nil unless data
     data["build"] ||= {}
     data["build"]["auto"] = false
+
+    # Release the worktrees the matching arm provisioned (intent 73c). Non-fatal:
+    # a release error must not block disarming. CLEANUP (73c3) refines the
+    # merge-vs-remove policy on the completion/release path.
+    begin
+      Worktree.release(data)
+    rescue => e
+      $stderr.puts "plastic: worktree release raised, continuing: #{e.message}"
+    end
+
     write(session, data)
     purge_done_bridges(session: session)
     data
@@ -489,6 +656,114 @@ module Bridge
       "(blocked edit: #{file_abs})"
   end
 
+  # --- Worktree isolation gate (intent 73c2) ---
+
+  # Returns a reason String to BLOCK, or nil to ALLOW. Two independent rules,
+  # both fail-open by construction:
+  #
+  #   1. When the bridge has a provisioned code worktree, a code edit (a target
+  #      outside ~/.plastic and outside this intent's store dir) MUST land inside
+  #      worktree["code"]; otherwise BLOCK and name the expected worktree path.
+  #   2. When the target lives inside ANOTHER intent's store dir whose bridge lock
+  #      is held by a LIVE non-owner session, BLOCK (non-owner edit to an active
+  #      intent).
+  #
+  # Fails open (returns nil) when provisioned is false (non-git / global-only) or
+  # the bridge carries no worktree/lock blocks. Logs nothing on the allow path.
+  def self.worktree_gate_decision(bridge_data, file_path, home: Dir.home, current_session: nil)
+    return nil unless bridge_data.is_a?(Hash)
+    return nil if blank?(file_path)
+
+    file_abs = File.expand_path(file_path.to_s)
+    plastic_home = File.expand_path(File.join(home, ".plastic"))
+    under_plastic = file_abs == plastic_home || file_abs.start_with?("#{plastic_home}/")
+
+    intent_info = bridge_data["intent"] || {}
+    store = intent_info["store"]
+    dir = intent_info["dir"]
+    intent_dir_abs = (store && dir) ? File.expand_path("#{store}/#{dir}") : nil
+    under_own_intent = intent_dir_abs &&
+                       (file_abs == intent_dir_abs || file_abs.start_with?("#{intent_dir_abs}/"))
+
+    # Rule 1: provisioned code worktree confines project-code edits.
+    worktree = bridge_data["worktree"] || {}
+    if worktree["provisioned"] == true
+      code = worktree["code"].to_s
+      # Project code = outside ~/.plastic and outside this intent's store dir.
+      is_project_code = !under_plastic && !under_own_intent
+      if is_project_code && !blank?(code)
+        code_abs = File.expand_path(code)
+        inside_code = file_abs == code_abs || file_abs.start_with?("#{code_abs}/")
+        unless inside_code
+          id = intent_info["id"]
+          return "intent #{id} is isolated to its worktree — edit project code " \
+                 "inside #{code_abs}, not the shared checkout. (blocked edit: #{file_abs})"
+        end
+      end
+    end
+
+    # Rule 2: do not edit another intent's locked, live store dir.
+    if under_plastic
+      reason = non_owner_store_edit_reason(file_abs, plastic_home, intent_dir_abs,
+                                           home: home, current_session: current_session,
+                                           own_session: bridge_data["session"])
+      return reason if reason
+    end
+
+    nil
+  end
+
+  # Helper for rule 2. A store dir is `<plastic_home>/store/{id}--{slug}` (global)
+  # or `<plastic_home>/projects/{slug}/store/{id}--{slug}` (project). When the
+  # edit target sits inside such a dir that is NOT this intent's own dir, and a
+  # live non-owner session holds that intent's bridge lock, BLOCK.
+  def self.non_owner_store_edit_reason(file_abs, plastic_home, own_intent_dir_abs,
+                                       home:, current_session:, own_session:)
+    return nil if own_intent_dir_abs &&
+                  (file_abs == own_intent_dir_abs || file_abs.start_with?("#{own_intent_dir_abs}/"))
+
+    parsed = parse_store_target(file_abs, plastic_home)
+    return nil unless parsed
+
+    session = blank?(current_session) ? own_session : current_session
+    held = Worktree.lock_held_by_other?(
+      intent_id: parsed[:id], store: parsed[:store],
+      current_session: session, home: home,
+    )
+    return nil unless held
+
+    "intent #{parsed[:id]} is owned by another live session — its delivery lock " \
+      "is held elsewhere. Back off; do not edit #{file_abs}."
+  end
+
+  # Resolve an edit target inside a store to {id:, store:} for the intent dir it
+  # belongs to, or nil if the path is not inside an `{id}--{slug}` intent dir.
+  def self.parse_store_target(file_abs, plastic_home)
+    rels = []
+    global_store = File.join(plastic_home, "store")
+    if file_abs.start_with?("#{global_store}/")
+      rels << [file_abs[(global_store.length + 1)..], global_store]
+    end
+    projects = File.join(plastic_home, "projects")
+    if file_abs.start_with?("#{projects}/")
+      tail = file_abs[(projects.length + 1)..].to_s
+      parts = tail.split(File::SEPARATOR)
+      if parts.length >= 2 && parts[1] == "store"
+        pstore = File.join(projects, parts[0], "store")
+        rels << [file_abs[(pstore.length + 1)..], pstore]
+      end
+    end
+
+    rels.each do |rel, store_dir|
+      next if blank?(rel)
+      first = rel.split(File::SEPARATOR).first.to_s
+      idx = first.index("--")
+      next unless idx && idx > 0
+      return { id: first[0...idx], store: store_dir }
+    end
+    nil
+  end
+
   # --- Bash-edit gate (intent 27a) ---
 
   # Extract the set of file paths a Bash command writes to. Conservative by

package/scripts/lib/installer_core.rb

@@ -203,13 +203,17 @@ class InstallerCore
       "scripts/hook-continue" => "scripts/hook-continue",
       "scripts/hook-future-intent-check" => "scripts/hook-future-intent-check",
       "scripts/hook-gate-check" => "scripts/hook-gate-check",
+      "scripts/hook-savepoint-pre" => "scripts/hook-savepoint-pre",
       "scripts/hook-qmd-search" => "scripts/hook-qmd-search",
       "scripts/lib/qmd_hook.rb" => "scripts/lib/qmd_hook.rb",
       "scripts/lib/power_tools.rb" => "scripts/lib/power_tools.rb",
       "scripts/hook-code-gate" => "scripts/hook-code-gate",
       "scripts/hook-bash-gate" => "scripts/hook-bash-gate",
+      "scripts/hook-retrieval-gate" => "scripts/hook-retrieval-gate",
+      "scripts/lib/retrieval_gate.rb" => "scripts/lib/retrieval_gate.rb",
       "scripts/hook-auto-arm" => "scripts/hook-auto-arm",
       "scripts/lib/bridge.rb" => "scripts/lib/bridge.rb",
+      "scripts/lib/worktree.rb" => "scripts/lib/worktree.rb",
       "scripts/lib/boot_banner.rb" => "scripts/lib/boot_banner.rb",
       "scripts/lib/qmd_sync.rb" => "scripts/lib/qmd_sync.rb",
       "scripts/qmd-sync" => "scripts/qmd-sync",
@@ -561,6 +565,15 @@ class InstallerCore
             { "type" => "command", "command" => "#{hook_dir}/plastic-create-gate", "statusMessage" => "Checking create gate..." },
           ],
         },
+        # Retrieval gate (intent 84, Lever 2): redirects store-markdown reads to
+        # QMD and code reads to Serena when those tools are present. Binds the
+        # main agent AND subagents (PreToolUse applies to subagent tool calls).
+        {
+          "matcher" => "Bash|Read|Grep|Glob",
+          "hooks" => [
+            { "type" => "command", "command" => "#{hook_dir}/plastic-retrieval-gate", "statusMessage" => "Checking retrieval gate..." },
+          ],
+        },
       ],
       "PostToolUse" => {
         "matcher" => "Write|Edit",

package/scripts/lib/qmd_sync.rb

@@ -120,6 +120,21 @@ module QmdSync
     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,238 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "bridge"
+
+# RetrievalGate — the single, pure decision for Lever 2 of intent 84.
+#
+# 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/Serena reason
+# String) or ALLOW it (returning nil). All capability and 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).
+#
+# Classification (per target path):
+#   - store `*.md` (under <plastic_home>/store or .../projects/<slug>/store) -> QMD
+#   - Serena-supported code/data file (NOT a store markdown) -> SERENA
+#   - images / binary / other -> ALLOWED
+#
+# Capability enforcement is BINARY (no advisory tier):
+#   - QMD class: detected+fresh -> BLOCK; detected+stale -> fire reindex, ALLOW
+#     this turn; absent/down -> ALLOW (no warning).
+#   - SERENA class: detected -> BLOCK; absent -> ALLOW.
+#
+# Bypass: a TRAILING `# qmd-ok` shell comment on a Bash command (not a substring;
+# a quoted/echoed occurrence does not bypass).
+#
+# 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
+
+  # Serena LSP covers many languages incl. JSON/YAML/TOML/Markdown/Ruby. Keep a
+  # small, conservative allowlist of code/data extensions. Markdown is listed but
+  # store markdown is reclassified to QMD before Serena ever sees it.
+  SERENA_EXTENSIONS = %w[
+    rb js jsx ts tsx mjs cjs py go rs java kt scala c h cpp hpp cc
+    cs php rb swift sh bash zsh lua ex exs erl clj sql
+    json yaml yml toml md markdown
+  ].freeze
+
+  # Image / binary extensions that are always allowed (plain read is fine).
+  BINARY_EXTENSIONS = %w[
+    png jpg jpeg gif webp svg ico bmp tiff pdf
+    zip gz tar tgz bz2 xz 7z
+    mp3 mp4 mov avi wav flac ogg
+    woff woff2 ttf otf eot
+    bin exe dll so dylib o a class jar wasm
+  ].freeze
+
+  # 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
+
+  # Decide. Returns nil to ALLOW, or a reason String to BLOCK.
+  #   capabilities: { qmd:, qmd_fresh:, serena: } (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|
+      case classify(path, plastic_home: plastic_home)
+      when :qmd
+        if capabilities[:qmd] && capabilities[:qmd_fresh]
+          return qmd_reason(path)
+        elsif capabilities[:qmd] # present but stale
+          stale_seen = true
+        end
+        # absent/down -> allow this target
+      when :serena
+        return serena_reason(path) if capabilities[:serena]
+      end
+    end
+
+    reindex.call if stale_seen
+    nil
+  end
+
+  # --- classification ---
+
+  def classify(path, plastic_home:)
+    return :allow if path.nil? || path.empty?
+    ext = extension(path)
+
+    if store_markdown?(path, plastic_home: plastic_home)
+      return :qmd
+    end
+    return :allow if BINARY_EXTENSIONS.include?(ext)
+    return :serena if SERENA_EXTENSIONS.include?(ext)
+
+    :allow
+  end
+
+  # A markdown file under the global store or a project store. QMD owns store
+  # markdown even though Serena could also read markdown (QMD wins for the store).
+  def store_markdown?(path, plastic_home:)
+    return false unless %w[md markdown].include?(extension(path))
+    abs = absolutize(path)
+    home = File.expand_path(plastic_home)
+    global = File.join(home, "store")
+    return true if 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 extension(path)
+    File.extname(path.to_s).sub(/\A\./, "").downcase
+  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 the call reads/scans. Conservative: missing an exotic form is fine;
+  # never flag /dev/null or pure pipes. Read vectors only (this is a READ gate),
+  # not the write vectors bridge.rb already covers.
+  def extract_targets(tool_name, tool_input, cwd:)
+    input = tool_input.is_a?(Hash) ? tool_input : {}
+    case tool_name.to_s
+    when "Read"
+      [input["file_path"]].compact.reject(&:empty?)
+    when "Glob"
+      [input["path"], input["pattern"]].compact.reject { |s| s.to_s.empty? }
+    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_read_targets(input["command"].to_s)
+    else
+      []
+    end
+  end
+
+  # READ utilities that take file/dir path arguments. Conservative parse: split
+  # on shell separators, identify the utility, collect its non-flag path args.
+  READ_UTILS = %w[grep rg ag find cat head tail less more bat ls wc nl sort uniq].freeze
+
+  def bash_read_targets(command)
+    return [] unless command.is_a?(String) && !command.empty?
+    targets = []
+    command.split(/[;\n]|&&|\|\||\|/).each do |segment|
+      targets.concat(segment_read_targets(segment))
+    end
+    targets.reject { |t| t.nil? || t.empty? || dev_path?(t) }.uniq
+  end
+
+  def segment_read_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 READ_UTILS.include?(util)
+
+    args = tokens[(idx + 1)..] || []
+    path_args_for(util, args)
+  end
+
+  # Collect path-shaped arguments for a read utility. Flags and flag-values are
+  # skipped; for grep/rg the first non-flag bareword is the PATTERN, not a path.
+  def path_args_for(util, args)
+    skip_pattern = %w[grep rg ag].include?(util)
+    paths = []
+    pattern_consumed = false
+    args.each do |a|
+      next if a.start_with?("-")
+      if skip_pattern && !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 raw grep/Read. " \
+      "Use `qmd search`/`qmd query` over the `plastic-*` collections (or " \
+      "`scripts/qmd-sync search`) instead of reading #{path}. " \
+      "If you genuinely need the raw read, append a trailing `# qmd-ok` to a Bash command."
+  end
+
+  def serena_reason(path)
+    "retrieval gate: navigate code via Serena's symbolic tools (find_symbol / " \
+      "get_symbols_overview / find_referencing_symbols), not raw grep/Read of #{path}."
+  end
+end