@zalom/plastic 1.0.0-beta.12 → 1.0.0-beta.14

package/PLASTIC.md

@@ -183,6 +183,10 @@ Sections: `## Active`, `## Future`, `## Clusters`, `## Abandoned`, `## Completed
 
 For index maintenance, use `plastic-managing-index`.
 
+One-line entry convention. Each index entry is ONE line: `- [<id> <terse title>](<dir>) <tags>`.
+The title is the title, not a summary: aim for about 80 characters, no multi-sentence
+descriptions. This is a self-check, not a gate.
+
 ## Rules for Skills
 
 ALL work flows through intents.
@@ -194,6 +198,53 @@ ALL work flows through intents.
 5. Researches are intents. No separate folder.
 6. Intents are created only via `plastic-creating-intent`. Never hand-author an intent file. The skill self-verifies the written intent with `scripts/validate-intent` before announcing or committing, so every intent is born complete.
 
+## House Style (self-check)
+
+The agent is the heaviest contributor to the transcript, so terseness pays every turn. These
+are pre-send self-checks the agent applies to its own output. They are not gated.
+
+- Answer or decision first. Lead with the result, then support it.
+- Bullets over paragraphs.
+- No preamble, no end-recap. Do not restate the question or summarize what you just said.
+- One question-cluster at a time when asking the human.
+- Reasoning goes in the thinking channel, not duplicated into the visible reply. This keeps
+  the human's visibility into your reasoning without paying for it twice in the transcript.
+
+Active-intent cache rule. For the intent under active development you already hold its
+delivered artifacts in your own context: prefer revisiting that in-context memory (hit the
+cache) over re-reading them from disk, which only widens context. QMD is for OTHER or indexed
+intents, not for re-reading what you just wrote. Pairs with `/clear` plus savepoint-resume
+hygiene after each intent. Advisory self-check, not hard-verifiable.
+
+## Retrieval Gate
+
+A single capability-aware PreToolUse gate enforces retrieval-first routing on the agent's own
+Bash/Read/Grep/Glob calls (and on subagents, since PreToolUse binds them). Detection is binary:
+present means enforce, absent or down means off, with no warning and no advisory tier.
+
+- Store markdown (under a Plastic store) routes to QMD when QMD is present and the index is
+  fresh: the raw grep/find/Read is blocked and you use `qmd search`/`qmd query` (or
+  `scripts/qmd-sync search`) instead. When QMD is present but stale, the read is allowed this
+  turn and a background reindex is fired so the next turn enforces against a fresh index;
+  reindex is never synchronous. When QMD is absent or down, raw reads are allowed.
+- Serena-supported code and data files route to Serena symbolic tools when Serena is present;
+  absent means allowed.
+- Images, binaries, and everything else are allowed.
+- Bypass: append a trailing `# qmd-ok` shell comment to a Bash command for the rare case where
+  QMD is healthy but you genuinely need the raw read. A quoted or echoed occurrence does not
+  bypass. Bypasses are logged.
+- Scope: only the agent's tool calls. Ruby `File.read` inside a script is invisible to the gate
+  and is out of scope by 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).
+
 ## Transition Gates
 
 | Transition | Trigger | Gate |

package/hooks/hooks.json

@@ -40,6 +40,16 @@
           }
         ]
       },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" savepoint-pre",
+            "statusMessage": "Recording stage start..."
+          }
+        ]
+      },
       {
         "matcher": "Write",
         "hooks": [
@@ -59,6 +69,16 @@
             "statusMessage": "Checking lifecycle gate..."
           }
         ]
+      },
+      {
+        "matcher": "Bash|Read|Grep|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" retrieval-gate",
+            "statusMessage": "Checking retrieval gate..."
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/hooks/retrieval-gate

@@ -0,0 +1,10 @@
+#!/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

@@ -0,0 +1,10 @@
+#!/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.14",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/hook-gate-check

@@ -24,6 +24,12 @@ intent_dir_abs = Bridge.intent_dir_for(file_path_abs)
 if intent_dir_abs
   begin
     Bridge.append_savepoint(intent_dir_abs, file_path_abs)
+    # When checklist.md lands, How ends and Exec begins: emit the `Exec started`
+    # companion in the same event (intent 81). Guard on a real (non-placeholder)
+    # checklist so a scaffold sentinel does not trip it.
+    if File.basename(file_path_abs) == "checklist.md" && Bridge.stage_file_present?(file_path_abs)
+      Bridge.append_exec_started(intent_dir_abs)
+    end
   rescue StandardError
     # ignore — rebuildable from disk
   end
@@ -112,32 +118,17 @@ if is_stage_file || is_action_file
 
   Bridge.write(session, bridge_data)
 
-  # Build transition context
-  stage_labels = { "what" => "What", "why" => "Why", "how" => "How", "exec" => "Exec", "done" => "Done" }
-  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."
-  }
-
-  context_parts = ["PLASTIC"]
-  if old_stage != new_stage
-    context_parts[0] = "PLASTIC — Stage transition: #{stage_labels[old_stage] || old_stage} → #{stage_labels[new_stage] || new_stage}."
-  else
-    context_parts[0] = "PLASTIC — #{basename} written (stage: #{stage_labels[new_stage] || new_stage})."
-  end
-  context_parts << "#{basename} written."  if old_stage != new_stage
-  if new_missing.any?
-    context_parts << "Next: #{new_missing.join(", ")}"
-  elsif next_hints[new_stage]
-    context_parts << "Next: #{next_hints[new_stage]}"
-  end
+  # Build transition context — ONE concise sentence (intent 84, Lever 1),
+  # preserving the `Next: ...` hint. Formatting is pure in Bridge.gate_narration.
+  context = Bridge.gate_narration(
+    old_stage: old_stage, new_stage: new_stage,
+    basename: basename, new_missing: new_missing
+  )
 
   payload = {
     "hookSpecificOutput" => {
       "hookEventName" => "PostToolUse",
-      "additionalContext" => context_parts.join(" ")
+      "additionalContext" => context
     }
   }
   puts JSON.generate(payload)

package/scripts/hook-retrieval-gate

@@ -0,0 +1,122 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# PreToolUse retrieval gate (intent 84, Lever 2). Reads the tool call (JSON on
+# stdin: tool_name + tool_input), computes capabilities (QMD detect+freshness,
+# Serena detect), delegates the decision to RetrievalGate, and enforces:
+#   ALLOW = exit 0 ; BLOCK = exit 2 with reason on stderr (shown to the agent).
+# 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).
+#
+# 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"
+require_relative "lib/power_tools"
+
+module RetrievalGateHook
+  module_function
+
+  # Pure-ish core: capabilities and reindex are injected so this is unit-testable
+  # with no real qmd/serena. Returns [exit_code, stderr_string].
+  #   stdin: raw PreToolUse JSON
+  #   capabilities: { qmd:, qmd_fresh:, serena: }
+  #   reindex: callable fired on the STALE path
+  def run(stdin:, plastic_home:, cwd:, capabilities:, reindex: -> {})
+    payload = parse(stdin)
+    return [0, 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
+      [2, "PLASTIC GATE — #{reason}"]
+    elsif bypassed
+      [0, "PLASTIC GATE — bypassed via # qmd-ok"]
+    else
+      [0, nil]
+    end
+  rescue StandardError
+    [0, 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. A slow `qmd status` cannot
+  # stall a tool call: a Timeout around the freshness probe degrades to "absent
+  # for this turn" (allow, no reindex), staying fail-open and non-blocking.
+  def detect_capabilities(cwd:)
+    qmd = QmdSync.detect
+    qmd_fresh = false
+    if qmd
+      qmd_fresh = begin
+        Timeout.timeout(2) { QmdSync.fresh? }
+      rescue StandardError
+        # Probe stalled/failed: treat as absent this turn (allow, no reindex).
+        qmd = false
+        false
+      end
+    end
+    serena = PowerTools.serena?(cwd: cwd)
+    { qmd: qmd, qmd_fresh: qmd_fresh, serena: serena }
+  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 = 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] # fail-open at the outermost boundary too
+  end
+
+  $stderr.puts(err) if err && !err.empty?
+  exit code
+end

package/scripts/hook-savepoint-pre

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

package/scripts/lib/bridge.rb

@@ -274,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
@@ -306,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)
@@ -315,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

package/scripts/lib/installer_core.rb

@@ -203,11 +203,14 @@ 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",
@@ -219,6 +222,8 @@ class InstallerCore
       "scripts/lib/frontmatter_writer.rb" => "scripts/lib/frontmatter_writer.rb",
       "scripts/lib/links_projection.rb" => "scripts/lib/links_projection.rb",
       "scripts/lib/links_section.rb" => "scripts/lib/links_section.rb",
+      "scripts/project-links" => "scripts/project-links",
+      "scripts/rebuild-graph" => "scripts/rebuild-graph",
       "scripts/validate-intent" => "scripts/validate-intent",
       "scripts/new-intent" => "scripts/new-intent",
       "scripts/hook-create-gate" => "scripts/hook-create-gate",
@@ -562,6 +567,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
+  ].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

package/scripts/new-intent

@@ -311,7 +311,15 @@ def main(argv)
     File.write(File.join(intent_dir, name), "#{Bridge::PLACEHOLDER_SENTINEL}\n#{body}")
   end
 
-  # 6. Self-validate (frontmatter + sanctioned sections).
+  # 6. Stamp the born savepoint line (intent 81). The first ledger line is the
+  # `What` bookend, written deterministically at creation rather than relying on
+  # a PostToolUse gate firing on the intent-file write (which is missed in some
+  # sessions / harnesses). The intent file is never a sentinel placeholder, so
+  # append_savepoint records `What  {id}--{slug}.md`. Idempotent: a later gate
+  # fire adds nothing.
+  Bridge.append_savepoint(intent_dir, intent_file)
+
+  # 7. Self-validate (frontmatter + sanctioned sections).
   result = IntentValidator.validate(intent_dir)
   unless result[:ok]
     warn "new-intent: scaffolded intent is NOT born complete:"

package/scripts/spawn-preamble

@@ -43,8 +43,10 @@ REPORT_CONTRACT =
   "status (delivered or blocked), artifacts written, verification or tests run, " \
   "checklist deltas, deviations from spec, and blockers or handoff notes; plus a " \
   "role-specific payload that fulfils your place in the What, Why, How, Exec cycle " \
-  "(for example the planner explains the plan back to the orchestrator). See " \
-  "skills/auto/references/agent-report-contract.md for the per-role format."
+  "(for example the planner explains the plan back to the orchestrator). Keep the " \
+  "report prose-stripped: the envelope and payload only, no greeting, no preamble, " \
+  "no end-recap, no restating of the task; reasoning stays in the thinking channel. " \
+  "See skills/auto/references/agent-report-contract.md for the per-role format."
 
 def parse_args(argv)
   role = nil

package/skills/auto/SKILL.md

@@ -90,7 +90,19 @@ Solo fallback: if the harness has no subagent dispatch, fall back to a single ag
 
 ## Stage-Aware Entry
 
-Read the active intent's directory. Determine current lifecycle stage from filesystem state:
+Read the active intent's `savepoint.md` FIRST (intent 81): the last line classifies the stage,
+and you then verify only that line's artifact before entering. Fall back to the filesystem probe
+below only when the ledger is missing (then rebuild it with `Bridge.rebuild_savepoint`).
+
+| Ledger last line | Enter |
+|---|---|
+| `What  {id}--{slug}.md` (born) or no spec | Start / complete Why (write spec.md) |
+| `Why  spec.md created` | Enter How |
+| `How  plan.md created` / `How  checklist.md created` / `Exec  started` | Enter Exec (verify plan + checklist) |
+| `Exec  outcome.md created` | Exec done; complete the intent |
+| `Done  delivered|abandoned` | Terminal; do not resume |
+
+Filesystem fallback (ledger missing only):
 
 | Check (in order) | Stage |
 |---|---|
@@ -196,7 +208,13 @@ During initial project creation, all decisions are non-destructive by definition
 5. Review `## Insights` for observations that should spawn future intents. If any:
    - Create them (using `plastic-creating-intent` conventions)
    - Update `chain` in the current intent's frontmatter
-6. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
+6. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date). As the
+   closing act of the transfer, stamp the terminal ledger bookend (intent 81) so the savepoint's
+   last line records delivery:
+   ```bash
+   ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.append_terminal_savepoint("<intent_dir>", "delivered")'
+   ```
+   (Use `"abandoned"` instead when the intent is being moved to `## Abandoned`.) Idempotent.
 7. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: deliver intent <ID> — <name>"`
 8. On completion, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent).
    It runs in the background so it never blocks the turn:

package/skills/auto/references/agent-report-contract.md

@@ -17,6 +17,14 @@ only. In-flight observations still go in `## Insights`; the report does not add
 completed its handoff: the agent that did the work is the cheapest, most accurate source of the
 account.
 
+## Prose-stripped (intent 84)
+
+The report is the envelope and the per-role payload, nothing else. Dispatched and background
+subagents report and do their job; they do not narrate. Strip conversational prose: no
+greeting, no preamble, no "Here is what I did" framing, no end-recap, no restating of the task.
+Reasoning belongs in the thinking channel, not the report body. This tightens the FORM (the
+fields stay exactly as below); it does not remove any required field.
+
 ## Common envelope
 
 Every role report, whatever the stage, carries these fields:

package/skills/continuing/SKILL.md

@@ -63,13 +63,28 @@ command is a no-op when QMD is absent, so fall back to the existing INDEX.md / f
 
 For that intent's directory:
 
-1. **Read `savepoint.md`.** It is a deterministic, append-only stage ledger (one line per
-   milestone, newest at the bottom): `{utc-iso8601}  {Stage}  {milestone}`. The **last line =
-   current stage**.
-2. **Verify the stage file.** Confirm the file the ledger names exists and is non-empty
-   (ledger `How  plan.md created` → `plan.md` must be present and non-empty).
+1. **Read `savepoint.md` FIRST (intent 81).** It is a deterministic, append-only ledger
+   (one line per event, newest at the bottom): `{utc-iso8601}  {Stage}  {milestone}`. Classify
+   the state from the **last line** alone, then verify ONLY that line's artifact. The bookends
+   are fixed: first line `What  created`, last line either a cycle position or
+   `Done  delivered|abandoned`.
+
+   | Last line | State | Verify only |
+   |---|---|---|
+   | `What  {id}--{slug}.md` | born / parked | intent file exists |
+   | `Why  started` | Why entered, no spec yet | spec.md not yet real; continue Why |
+   | `Why  spec.md created` | Why done | spec.md present; continue to How |
+   | `How  started` / `How  plan.md created` | How in progress | plan.md; continue How |
+   | `How  checklist.md created` / `Exec  started` | ready for / in Exec | plan.md + checklist.md present; continue Exec |
+   | `Exec  outcome.md created` | Exec done | outcome.md present; ready to complete |
+   | `Done  delivered` / `Done  abandoned` | terminal | do NOT cycle-resume; INDEX is authoritative |
+
+2. **Verify the stage file.** Confirm only the last line's artifact exists and is non-empty
+   (ledger `How  plan.md created` → `plan.md` must be present and non-empty). Do not re-probe
+   every lifecycle file.
 3. **Drift handling.** If the ledger's last line disagrees with files-on-disk, rebuild the
-   ledger from filesystem state and note the correction:
+   ledger from filesystem state and note the correction. A rebuilt ledger is the file-landing
+   skeleton (no `started`/`Done` lines), which still pins cycle position:
    ```bash
    ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.rebuild_savepoint("<intent_dir>")'
    ```

package/skills/intent-curator/SKILL.md

@@ -38,6 +38,9 @@ The agent handles:
 - Cluster management (create, merge, rename)
 - Orphan detection
 
-When an intent reaches a terminal state — moved to Completed OR Abandoned — refresh the QMD index for the affected store (no-op when QMD absent), running in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`.
+When an intent reaches a terminal state — moved to Completed OR Abandoned — do two things as the closing act of the transfer:
+
+1. Stamp the terminal savepoint bookend (intent 81), so the ledger's last line records the disposition: `ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.append_terminal_savepoint("<intent_dir>", "delivered")'` (use `"abandoned"` for an abandoned intent). Idempotent.
+2. Refresh the QMD index for the affected store (no-op when QMD absent), running in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`.
 
 After the agent completes, report what changed.

package/skills/managing-index/SKILL.md

@@ -41,6 +41,8 @@ Topic-based groupings. Manually curated. Create a new cluster when 3+ intents sh
 ### Completed
 All completed intents with dates. Links preserved, never deleted.
 
+When you move an intent INTO Completed or Abandoned, stamp the terminal savepoint bookend as the closing act of the transfer (intent 81), so the ledger's last line records the disposition: `ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.append_terminal_savepoint("<intent_dir>", "delivered")'` (use `"abandoned"` for an abandoned intent). Idempotent.
+
 ## Workflow
 
 QMD-first (when available): when you need to locate a specific intent (to reclassify, flag, or