@zalom/plastic 1.8.0 → 1.9.0

package/skills/intent-savepoint/SKILL.md

@@ -22,6 +22,10 @@ It is **sugar on top of the conventions**, not a source of truth. The gate hook
 nothing to save by hand. State is always derivable from files-on-disk; the ledger just lets
 a resuming agent read the cycle's succession from one glance (last line = where we are).
 
+Read `../plastic-conventions/references/lifecycle-and-savepoints.md` for the subagent
+report-home contract that this ledger feeds. This path resolves relative to this skill's own
+installed directory.
+
 ## When to Use
 - A PreCompact hook fires, or the user says "save" / "savepoint": verify the ledger is current.
 - Resuming an intent: read the ledger to learn the cycle's succession quickly.

package/skills/intent-speccing/SKILL.md

@@ -47,6 +47,10 @@ not the Transition Gates table row). Writing `plan.md` is what opens the code ga
 writing `plan.md` is not this skill's job, that is `plastic-intent-planning`. State this to the user
 at step 6 so the handoff at step 8 is expected, not a surprise.
 
+Read `../plastic-conventions/references/lifecycle-and-savepoints.md` for the subagent
+report-home contract behind this handoff. This path resolves relative to this skill's own
+installed directory.
+
 ## Tier stamp (step 3, convention only)
 
 Write `Tier: S|M|L` as the literal first line of the file, above the `# Spec:` heading. This line

package/skills/intent-starting/SKILL.md

@@ -32,6 +32,10 @@ The lock is non-negotiable and comes before any mutating work. The ACTION-3 lock
 enforces it: without a held lock, mutating writes to this active intent's dir are denied with
 "run /plastic-intent-starting to lock and begin".
 
+Read `../plastic-conventions/references/locks-and-worktrees.md` for delivery isolation: the
+single-owner lock, claims, worktrees, solo mode, and the station ledger behind everything below.
+This path resolves relative to this skill's own installed directory.
+
 1. **Ensure the intent is in INDEX `## Active`.** If it sits in `## Future`, activate it
    (move it to `## Active`, auto-commit) before arming. Creation precedes activation, so a
    brand-new What intent is activated here, then locked.
@@ -106,12 +110,18 @@ Never re-ask at a later station.
 - **auto** → `arm_auto` (lock + auto), then hand off to `plastic-auto`. The auto branch's
   only remaining job is the handoff; `plastic-auto` runs the cycle from here.
 
+Read `../plastic-conventions/references/tiers-and-dispatch.md` for tier sizing and the
+stage-to-agent dispatch rules behind the auto branch above.
+
 ## Board at the latest delivered station
 
 The station is derived from `savepoint.md` last line + real artifacts on disk. See
 `references/boarding-matrix.md` for the full table (last line → latest delivered → boards at →
 continue with) and the per-station notes. Summary of what "continue" means per station:
 
+Read `../plastic-conventions/references/gates-and-enforcement.md` for the transition-gate
+mechanics, the audited escape, and gate logging that govern moving between the stations below.
+
 - **What** → do what What requires (106-expanded), then brainstorm → `spec.md`.
 - **Why** → continue brainstorming → `spec.md`.
 - **How** → continue `plan.md` + `actions/` + `checklist.md`.

package/skills/project-creating/references/project-scaffolding.md

@@ -17,8 +17,8 @@ Create `AGENTS.md` in the project root with:
 ```markdown
 # <Project Name> — Agent Instructions
 
-Read `PLASTIC.md` in `~/.plastic/`. It contains all Plastic conventions.
-Follow it exactly.
+Read `PLASTIC.md` in `~/.plastic/` for the core conventions; deeper doctrine lives in
+the `plastic-conventions` skill's chapters. Follow it exactly.
 
 This file is the operating contract for this project. Any agent entering
 this project reads this file first.

package/skills/roadmap/SKILL.md

@@ -43,6 +43,10 @@ See `references/file-format.md` for the exact entry-line shape, status vocabular
 format, and a worked example. See `references/operations.md` for step-by-step mechanics of each
 verb above.
 
+Read `../plastic-conventions/references/roadmaps.md` for the roadmap file format, batch
+semantics, and the status-mirror rule that this skill's own file-format reference builds on. This
+path resolves relative to this skill's own installed directory.
+
 ## Notes
 
 - File location and the four-section shape are identical across tiers; do not invent a different

package/skills/roadmap-continuing/SKILL.md

@@ -45,6 +45,10 @@ roadmap handoff had to be resumed by hand, carried as a free-prose note in `171`
 4. A genuine tie (two candidates equally live) is presented to the user and resolved by the
    single ask below, not silently picked.
 
+Read `../plastic-conventions/references/roadmaps.md` for the roadmap file format, batch
+semantics, and the status-mirror rule behind the candidates gathered above. This path resolves
+relative to this skill's own installed directory.
+
 ## Present state
 
 Present the chosen roadmap's `## Goal`, the current batch with each entry's mirrored status, the

package/skills/skill-creating/SKILL.md

@@ -49,6 +49,9 @@ routes each authoring task to the reference that holds the depth.
 | Deciding script versus prose, or writing a script | `references/scripts.md` |
 | Building evals for a skill | `references/evals.md` |
 
+Read `references/defaults-first.md` before naming an external skill as a default, for the
+Plastic-first, delegate-by-exception rule.
+
 ## Shrink context, or let a skill self-improve
 
 - When prompts or tool output blow the context budget, open `references/hooks.md` (E7) for

package/skills/skill-creating/references/defaults-first.md

@@ -0,0 +1,23 @@
+# Defaults First
+
+This chapter holds the Plastic-first, delegate-by-exception rule for naming an external skill as a default.
+
+### 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.

package/skills/skill-creating/references/hooks.md

@@ -77,7 +77,10 @@ Notes that change the choice of event: [E2]
 - PreCompact fires before the runtime compacts the conversation. Use it to write a savepoint
   while the full context still exists.
 
-Plastic ships working instances of each: `scripts/hook-code-gate` (PreToolUse gate),
+Plastic ships working instances of each: `hooks/edit-gates` -> `scripts/hook-edit-gates`
+(PreToolUse, the merged dispatcher that runs code-gate, lock-gate, savepoint-pre, links-gate,
+and create-gate in one process; each gate's own logic lives in `scripts/lib/edit_gates.rb`
+and is also reachable through the standalone `scripts/hook-code-gate` CLI wrapper),
 `scripts/hook-session-start` (SessionStart boot and inject), `scripts/hook-savepoint-pre`
 (PreCompact savepoint). Read one before authoring a new hook of the same shape.
 

package/skills/store-curating/SKILL.md

@@ -39,6 +39,10 @@ The agent handles:
 - Cluster management (create, merge, rename)
 - Orphan detection
 
+Read `../plastic-conventions/references/knowledge-graph.md` for the linking doctrine: tiers of
+influence, sources versus chain, and the `## Links` projection, before judging a link discovery or
+orphan finding. This path resolves relative to this skill's own installed directory.
+
 When an intent reaches a terminal state, moved to Completed OR Abandoned, do these things:
 
 1. Author a real `outcome.md` in the intent directory from `~/.plastic/templates/outcome.md`, with the frontmatter `disposition: delivered` for a completed intent or `disposition: abandoned` for an abandoned one. `outcome.md` is MANDATORY at every terminal, delivered and abandoned alike: on abandon it records the abandonment reason and replaces the scaffolded placeholder sentinel (never leave `outcome.md` a placeholder at a terminal).
@@ -54,3 +58,7 @@ follows its own step 7: it detects (never acquires) the target's delivery lock,
 clean working tree, and performs the fix on a fresh branch merged back to main as one closed
 operation, with an append-only `revisions.md` receipt in the same pass as the edit. See
 `agents/plastic-intent-curator.md` for the exact mechanics.
+
+Read `../plastic-conventions/references/maintenance-and-revisions.md` for WORK versus
+MAINTENANCE, the `revisions.md` move-and-record contract, and the violation-tag catalog before
+running a maintenance dispatch like this one.

package/skills/store-indexing/SKILL.md

@@ -75,8 +75,16 @@ When 3+ intents share tags but aren't in a cluster, suggest a new cluster headin
 ### Flag Orphans
 Intents with no links (empty `sources`, empty `chain`, no `## Links` entries, not in any cluster) should be flagged for curation.
 
+Before reclassifying a structural finding outside routine indexing, read
+`../plastic-conventions/references/maintenance-and-revisions.md` for WORK versus MAINTENANCE, the
+`revisions.md` move-and-record contract, and the violation-tag catalog.
+
 REQUIRED BACKGROUND: intent-linking (for understanding connection types and Zettelkasten theory)
 
+Read `../plastic-conventions/references/knowledge-graph.md` for the linking doctrine: tiers of
+influence, sources versus chain, and the `## Links` projection. This path resolves relative to
+this skill's own installed directory.
+
 ## References
 
 - Read `references/zettelkasten-linking.md` for the three structural layers (Folgezettel, directed graph, tags) and how they map to INDEX.md organization

package/skills/tutorial/references/track-2-auto.md

@@ -56,10 +56,9 @@ Checkpoint: name one thing auto will always stop and ask about, rather than deci
 No new command. Auto still honors every hard gate a guided session would hit: the delivery
 lock (one owner at a time), the code gate (shut until `plan.md` and `checklist.md` exist),
 and the create gate (intents only come from the tool that makes them, never hand-authored).
-One gate, retrieval, is advisory only and never blocks anything; it just adds a note.
 
-Checkpoint: read one gate message from the run so far and say whether it is one of the hard
-gates or the one advisory note.
+Checkpoint: read one gate message from the run so far and name which of the three gates it
+came from.
 
 ### 4. Reading the per-stage reports
 

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