@zalom/plastic 1.7.1 → 1.9.0

package/PLASTIC-reference.md

@@ -1,138 +0,0 @@
-# Plastic - Reference
-
-> **This file is maintained by Plastic.** It will be overwritten when the
-> plugin is updated. It holds reference material: read it on demand, it is
-> not injected at session start.
-
-### Structural maintenance and revisions.md
-
-When a delivered intent accumulates structural junk (an unsanctioned section, a stray file, a
-frontmatter edge to an intent that no longer exists), the intent-curator relocates it into
-`revisions.md` instead of reopening the work. Each entry is a versioned, dated header
-(`## Revision vN - YYYY-MM-DD-HH:MM`) plus `Why` (one sentence naming the broken rule, ending
-with `[rule: <tag>]`), `Prior location`, and either `Content held` (the verbatim removed
-content) or, for a frontmatter edit, a one-line `Change` (before and after). A stray file has
-its full content embedded and the original is deleted.
-
-Violation tags (starter set, free-text tags allowed):
-- `unsanctioned-section`: a top-level section the sanctioned-section rule now rejects
-- `phantom-section`: a section referenced but not present or not sanctioned
-- `stray-file`: a file that does not belong in the intent directory
-- `dangling-ref`: a link or reference to something that no longer exists
-- `broken-chain`: a chain frontmatter edge to an intent that no longer exists
-- `broken-source`: a sources frontmatter edge to an intent that no longer exists
-- `misplaced-content`: content that belongs in a different artifact or section
-- `links-projection`: a tool-authored `## Links` regeneration (project-links; intent 197)
-- `graph-rebuild`: a tool-authored sources/chain frontmatter rebuild (rebuild-graph; intent 197)
-
-## Two Processes
-
-| Process | Scope | Type | Actor |
-|---|---|---|---|
-| **Build → Observe → Repeat** | The system | Continuous loop | Coordinator |
-| **What → Why → How → Exec** | One intent | Finite lifecycle | Agent |
-
-B→O→R is the Coordinator's heartbeat. W→W→H→E is what happens inside each intent.
-The connection: an intent's `## Insights` feeds the Coordinator's Observe phase.
-
-## Defaults-First
-
-Plastic stands on its own. Skills and agents use Plastic's own defaults; an
-external skill (for example `superpowers:*`) is opt-in, never load-bearing.
-
-- **Default to Plastic, delegate by exception.** Name the Plastic-native path as
-  the default. Delegate to an external skill only when (a) it is available in the
-  harness, or (b) the user explicitly asks for it. A user without that plugin must
-  still get the core behavior.
-- **Phrase external skills as enhancements.** Write "use Plastic's native X by
-  default; if `superpowers:<skill>` is available, or the user prefers it, delegate
-  to it" never "delegate to `superpowers:<skill>`" as the only path.
-- **Optional dependencies detect then degrade.** `qmd` is the reference shape:
-  `scripts/lib/qmd_sync.rb` detects the binary first and every verb no-ops cleanly
-  when it is absent (see `scripts/qmd-sync`). Optional CLIs and MCP servers follow
-  the same detect-then-skip pattern, so a missing tool never crashes a session.
-- **Legitimate hard dependencies are exempt.** Ruby, Node, git, and POSIX tools are
-  the cost of running Plastic, not silent coupling. The principle targets accidental
-  dependence on external skills doing work Plastic should do itself.
-
-## Roadmaps
-
-Roadmaps exist for planned parallel delivery of intents in a coherent and organized way. A roadmap
-is a named, ordered, delivery-side collection of intents: the delivery-side counterpart to a
-release (completion-side, tracked in `CHANGELOG.md`). Use `plastic-roadmap` to create, order,
-close, and consume one.
-
-File location: `roadmaps/{slug}.md`, a sibling of `INDEX.md`, wherever `INDEX.md` lives, never
-inside `store/` (store holds intent directories, not project artifacts). For a project that is its
-root, `~/.plastic/projects/{slug}/roadmaps/`, beside `project.yml`; for the global tier it is
-`~/.plastic/roadmaps/`, beside `~/.plastic/INDEX.md`. `roadmaps/` lists only live (open or
-in-flight) roadmaps: once a roadmap's goal is reached, it moves to `roadmaps/archived/{slug}.md`,
-a sibling subdirectory scaffolded once with a `.gitkeep`.
-
-A roadmap file has four sections, in order: a title/meta header, `## Goal`, `## Batches`, and an
-append-only dated `## Log`. `## Goal` is a checkable prose condition read by a human or agent, not
-an executable checker. `## Batches` holds ordered batches; entries inside a batch are
-parallel-safe, batches run sequentially, top to bottom. A roadmap written before owner ruling 145
-may instead use the legacy `## Waves` heading; the tooling accepts both, but never renames an
-existing roadmap file to migrate it.
-
-Each batch entry carries a status token (`queued`/`delivering`/`delivered`/`abandoned`/`blocked`)
-that mirrors that intent's status in `INDEX.md`. `INDEX.md` is the single writer of intent status;
-on any conflict INDEX wins and the roadmap entry is corrected to match.
-
-**Human-comprehension surface.** A roadmap is also written to be read cold. Batch entries render as
-checkboxes (checked once delivered, unchecked otherwise) next to the status token, and each `## Log`
-line is one plain-language sentence, starting `YYYY-MM-DD HH:MM UTC`, written the way an
-engineering manager would brief a non-expert executive: what shipped and why it matters, no jargon
-or codenames, ending with a link
-to that intent's `outcome.md`. The log points at the detail instead of repeating it, so a person
-opening the file with no other context can tell what shipped, what is running now, and what is
-next in under a minute.
-
-**Relationship to loop engineering (intent 69).** A roadmap is the planning half of the work; the
-loop is its runtime. Batches lay out the parallelism plan: what can run together, and in what order.
-Loop engineering (intent 69, not yet delivered) is expected to consume that plan and supply the
-running parts, the heartbeat, how many dispatches run at once, checking the goal, and resuming
-after a stop. This section only states the relationship and points to intent 69 as the future
-consumer; it does not change intent 69's own design.
-
-## Context-economy measurement buckets (84a)
-
-Intent 84 defines three buckets for sibling 84a to audit against; 84 does not run the audit.
-
-- (a) gate-hook prose tokens: the per-transition narration emitted by the gate hook.
-- (b) main-loop store-read tokens: tokens the main agent spends reading or grepping the store
-  in the transcript.
-- (c) authored-section sizes: sizes of authored artifacts (INDEX entries and the like).
-
-## Deprecation Process
-
-Deprecations live in `deprecations.yml` and are shown at SessionStart. While Plastic is
-pre-1.0, a satisfied deprecation (its migration is already done on installed machines) may be
-removed immediately instead of waiting for its declared `removal` version. From `1.0.0` on,
-the steady-state grace rule applies (removal at least two minors ahead). For the full process,
-severity levels, and the pre-1.0 exception, see the `plastic-releasing` skill.
-
-## Skills Reference
-
-Detailed conventions live inside the skills that use them, not in this file.
-
-| Topic | Skill | References in skill |
-|-------|-------|-------------------|
-| Creating intents, lifecycle | `plastic-intent-creating` | lifecycle, wikilinks |
-| Brainstorming, spec writing | `plastic-intent-brainstorming` | — |
-| Planning, actions | `plastic-intent-planning` | — |
-| Execution, delivery | `plastic-intent-executing` | — |
-| Autonomous delivery | `plastic-auto` | agent architecture |
-| Save/restore state | `plastic-intent-savepoint`, `plastic-intent-continuing` | context management |
-| Knowledge graph, linking | `plastic-intent-linking` | zettelkasten, wikilinks |
-| Projects, hubs | `plastic-project-creating` | hubs, project stores |
-| Provision a project store | `plastic-store-provisioning` | project stores |
-| Index maintenance | `plastic-store-indexing` | — |
-| Releases, deprecations | `plastic-releasing` | deprecation process |
-| Health diagnostics | `plastic-doctor` | three scopes: `--core` (binary install-integrity check, runs on SessionStart), `--store [global\|<slug>]` (per-store check, runs on dashboard load), no flag = full check (runs after every update); gate enforcement, stuck detection |
-| Report a Plastic quirk, bug, or feature idea | `plastic-feedback` | transport and privacy (redaction checklist, why a prefilled URL) |
-| Authoring skills, agents, hooks | `plastic-skill-creating` | progressive disclosure, agentskills.io spec |
-| Evaluating skills, evals | `plastic-skill-evaluating` | eval methodology, convention checks |
-| Create, order, and consume a roadmap of intents | `plastic-roadmap` | file format, operations |
-

package/hooks/code-gate

@@ -1,27 +0,0 @@
-#!/bin/bash
-INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | ruby -rjson -e '
-  data = JSON.parse(STDIN.read)
-  ti = data["tool_input"] || data["tool_params"] || {}
-  path = ti["file_path"] || ti["notebook_path"] || ti["relative_path"] || ""
-  if !path.empty? && !path.start_with?("/")
-    root = ti["project_root"] || data["cwd"] || ""
-    path = File.join(root, path) unless root.empty?
-  end
-  puts path
-' 2>/dev/null)
-
-if [ -z "$FILE_PATH" ]; then
-  exit 0
-fi
-
-SESSION_ID=$(echo "$INPUT" | ruby -rjson -e 'data = JSON.parse(STDIN.read); puts data.dig("session_id") || ""' 2>/dev/null)
-
-NEW_CONTENT=$(echo "$INPUT" | ruby -rjson -e '
-  data = JSON.parse(STDIN.read)
-  ti = data["tool_input"] || data["tool_params"] || {}
-  print ti["content"] || ti["new_string"] || ""
-' 2>/dev/null)
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-ruby "$SCRIPT_DIR/../scripts/hook-code-gate" "$FILE_PATH" "$SESSION_ID" "$NEW_CONTENT"

package/hooks/create-gate

@@ -1,3 +0,0 @@
-#!/bin/bash
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-exec ruby "$SCRIPT_DIR/../scripts/hook-create-gate"

package/hooks/lock-gate

@@ -1,21 +0,0 @@
-#!/bin/bash
-INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | ruby -rjson -e '
-  data = JSON.parse(STDIN.read)
-  ti = data["tool_input"] || data["tool_params"] || {}
-  path = ti["file_path"] || ti["notebook_path"] || ti["relative_path"] || ""
-  if !path.empty? && !path.start_with?("/")
-    root = ti["project_root"] || data["cwd"] || ""
-    path = File.join(root, path) unless root.empty?
-  end
-  puts path
-' 2>/dev/null)
-
-if [ -z "$FILE_PATH" ]; then
-  exit 0
-fi
-
-SESSION_ID=$(echo "$INPUT" | ruby -rjson -e 'data = JSON.parse(STDIN.read); puts data.dig("session_id") || ""' 2>/dev/null)
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-ruby "$SCRIPT_DIR/../scripts/hook-lock-gate" "$FILE_PATH" "$SESSION_ID"

package/hooks/qmd-search

@@ -1,8 +0,0 @@
-#!/bin/bash
-# qmd-first search hook launcher (intent 66). No-op when there is no global store.
-GLOBAL_INDEX="$HOME/.plastic/INDEX.md"
-if [ ! -f "$GLOBAL_INDEX" ]; then
-  exit 0
-fi
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-exec ruby "$SCRIPT_DIR/../scripts/hook-qmd-search" "$HOME/.plastic"

package/hooks/retrieval-gate

@@ -1,10 +0,0 @@
-#!/bin/bash
-# Retrieval-gate hook launcher (intent 84, Lever 2). No-op when there is no
-# global store. Passes the PreToolUse JSON through on stdin (exec inherits it)
-# and the plastic_home as ARGV[0], mirroring the qmd-search launcher.
-GLOBAL_INDEX="$HOME/.plastic/INDEX.md"
-if [ ! -f "$GLOBAL_INDEX" ]; then
-  exit 0
-fi
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-exec ruby "$SCRIPT_DIR/../scripts/hook-retrieval-gate" "$HOME/.plastic"

package/hooks/savepoint-pre

@@ -1,10 +0,0 @@
-#!/bin/bash
-INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | ruby -rjson -e 'data = JSON.parse(STDIN.read); puts data.dig("tool_params", "file_path") || data.dig("tool_input", "file_path") || ""' 2>/dev/null)
-
-if [ -z "$FILE_PATH" ]; then
-  exit 0
-fi
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-ruby "$SCRIPT_DIR/../scripts/hook-savepoint-pre" "$FILE_PATH"

package/scripts/hook-qmd-search

@@ -1,44 +0,0 @@
-#!/usr/bin/env ruby
-# encoding: UTF-8
-# frozen_string_literal: true
-
-# qmd-first UserPromptSubmit hook (intent 66). Reads the prompt from stdin JSON,
-# delegates the decision to QmdHook.run under a hard timeout, and prints
-# hookSpecificOutput when there is something to inject/remind. Silent no-op (exit
-# 0) when qmd is absent, the prompt is trivial, or anything goes wrong. ARGV[0]
-# is the plastic_home (passed by the launcher); defaults to ~/.plastic.
-require "json"
-require "timeout"
-require_relative "lib/qmd_hook"
-
-raw = begin
-  STDIN.read
-rescue StandardError
-  ""
-end
-
-prompt = begin
-  parsed = JSON.parse(raw)
-  parsed.is_a?(Hash) ? parsed["user_prompt"].to_s : ""
-rescue StandardError
-  ""
-end
-
-plastic_home = (ARGV[0] && !ARGV[0].empty?) ? ARGV[0] : File.expand_path("~/.plastic")
-
-context = begin
-  Timeout.timeout(2) do
-    QmdHook.run(prompt: prompt, cwd: Dir.pwd, plastic_home: plastic_home)
-  end
-rescue Exception
-  nil
-end
-
-exit 0 if context.nil? || context.strip.empty?
-
-puts JSON.generate(
-  "hookSpecificOutput" => {
-    "hookEventName" => "UserPromptSubmit",
-    "additionalContext" => context,
-  }
-)

package/scripts/hook-retrieval-gate

@@ -1,148 +0,0 @@
-#!/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/lib/legacy_bookend_amnesty.rb

@@ -1,35 +0,0 @@
-# encoding: UTF-8
-# frozen_string_literal: true
-
-# Intent 170a - A2 cutoff amnesty for the legacy savepoint Done-bookend gap.
-#
-# Frozen 2026-07-10. Pre-161 terminal intents predate
-# Bridge.append_terminal_savepoint, so their savepoint.md never got a
-# `Done delivered|abandoned` line. This list grandfathers exactly those,
-# keyed by store scope plus intent id, so doctor's signals_complete check
-# stops counting them as gaps. Every intent NOT on this list still warns if
-# its savepoint lacks the Done bookend, including any new terminal intent
-# going forward. This is a frozen historical snapshot: it must never grow.
-# Regenerating it requires re-running the exact predicate below against the
-# real store and reviewing the diff, never appending ad hoc.
-#
-# Predicate used to build this list (2026-07-10): for each store in
-# Doctor#done_signal_stores(nil), each dir in index_sections_by_dir(index),
-# terminal = the dir's INDEX section is Completed or Abandoned, gap =
-# savepoint.md exists AND does not match
-# /\bDone\b.*\b(delivered|abandoned)\b/.
-#
-# This does NOT grandfather the separate outcome.md completeness gap
-# (checked independently at scripts/doctor.rb:603-607); some of these ids
-# may still warn on that axis.
-module LegacyBookendAmnesty
-  LIST = {
-    "global" => %w[1a 1a2 23].freeze,
-    "project:plastic" => %w[
-      1 11 121a 124 128 13 13b 15 158 158a 159 160 163 1a 1b1a3 22 30a1a 34
-      36a 36a1 37 38 39 45 45a 49 4a 4a1 4a1c1 50 52 54 55 56 58 59 60b 65
-      66 66a 66b 66c 66c1 67 68 71 72 73b 73c 73c1 73c2 73c3 74 77 79 80 83
-      84 85a 9
-    ].freeze,
-  }.freeze
-end

package/scripts/lib/retrieval_gate.rb

@@ -1,211 +0,0 @@
-# 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