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

package/scripts/agent-report

@@ -0,0 +1,163 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# agent-report - deterministic filesystem-derived completion report (intent 74).
+#
+# The auto-mode report contract is decision-shaped (the spawn preamble's
+# REPORT_CONTRACT plus the role prompts ask every dispatched agent to END with a
+# structured completion report). Because child-agent honor is best-effort across
+# harnesses (Tier B/C, docs/reference/harness-adapters.md), the contract is never a
+# hard block. This script is the always-a-report fallback: when a dispatched agent
+# returns no usable report, the enforcer runs it to synthesize one from the intent
+# directory, so the handoff account always exists.
+#
+# Like scripts/spawn-preamble, it is a PURE function of the intent dir: no network,
+# no randomness, no wall-clock reads. Two runs over the same on-disk state produce
+# byte-identical output.
+#
+# Usage:
+#   agent-report <intent_dir> [--role ROLE]
+#
+# Exit codes: 0 (report emitted), 2 (usage).
+
+require_relative "lib/bridge"
+
+def parse_args(argv)
+  role = nil
+  positional = []
+  i = 0
+  while i < argv.length
+    case argv[i]
+    when "--role"
+      role = argv[i + 1]
+      i += 2
+    else
+      positional << argv[i]
+      i += 1
+    end
+  end
+  [positional.first, role]
+end
+
+# Read the intent file frontmatter via the same path spawn-preamble uses, so the
+# id/intent we report match what the rest of Plastic sees. Never raises.
+def frontmatter_for(intent_dir)
+  ifile = Bridge.intent_file(intent_dir)
+  return {} unless File.exist?(ifile)
+
+  content = File.read(ifile)
+  return {} unless content.start_with?("---")
+
+  parts = content.split("---", 3)
+  return {} if parts.length < 3
+
+  require "yaml"
+  require "date"
+  require "time"
+  YAML.safe_load(parts[1], permitted_classes: [Date, Time]) || {}
+rescue StandardError
+  {}
+end
+
+# Current stage: prefer the last non-empty savepoint line (the ledger encodes the
+# furthest-reached milestone), else the file-derived stage. Same logic as
+# spawn-preamble's current_stage.
+STAGE_LABELS = {
+  "what" => "What", "why" => "Why", "how" => "How",
+  "exec" => "Exec", "done" => "Done"
+}.freeze
+
+def current_stage(intent_dir)
+  ledger = File.join(intent_dir, Bridge::SAVEPOINT_FILE)
+  if File.exist?(ledger)
+    last = File.read(ledger).each_line.map(&:strip).reject(&:empty?).last
+    return last if last
+  end
+  STAGE_LABELS.fetch(Bridge.derive_stage(intent_dir), Bridge.derive_stage(intent_dir))
+end
+
+# checklist.md checked/total: count GFM task-list items. Returns "n/a" when there
+# is no checklist (a checklist is only meaningful from How onward).
+def checklist_progress(intent_dir)
+  path = File.join(intent_dir, "checklist.md")
+  return "n/a" unless Bridge.stage_file_present?(path)
+
+  lines = File.readlines(path)
+  total = lines.count { |l| l =~ /^\s*- \[[ xX]\]/ }
+  checked = lines.count { |l| l =~ /^\s*- \[[xX]\]/ }
+  return "n/a" if total.zero?
+
+  "#{checked}/#{total}"
+end
+
+# The outcome line: first content line under outcome.md's "## Summary" (or the first
+# non-heading content line), else a placeholder. Pure read of the intent dir.
+def outcome_line(intent_dir)
+  path = File.join(intent_dir, "outcome.md")
+  return "(no outcome yet)" unless Bridge.stage_file_present?(path)
+
+  lines = File.readlines(path).map(&:rstrip)
+  start = lines.index { |l| l.strip.downcase == "## summary" }
+  scan = start ? lines[(start + 1)..] : lines
+  (scan || []).each do |l|
+    s = l.strip
+    next if s.empty? || s.start_with?("#") || s.start_with?("<!--")
+    return s
+  end
+  "(no outcome yet)"
+end
+
+# The insights line: the LAST line of the intent file's `## Insights` section
+# (the newest nugget, since entries are append-only newest-at-bottom), else
+# `(none)`. Pure read of the intent dir, no clock.
+def insights_line(intent_dir)
+  ifile = Bridge.intent_file(intent_dir)
+  return "(none)" unless File.exist?(ifile)
+
+  lines = File.read(ifile).split("\n", -1)
+  idx = lines.index { |l| l.strip == "## Insights" }
+  return "(none)" if idx.nil?
+
+  last = nil
+  (idx + 1).upto(lines.length - 1) do |i|
+    break if lines[i].start_with?("## ")
+
+    last = lines[i] unless lines[i].strip.empty?
+  end
+  last || "(none)"
+end
+
+intent_dir_arg, role = parse_args(ARGV)
+
+if intent_dir_arg.nil? || intent_dir_arg.empty?
+  warn "usage: agent-report <intent_dir> [--role ROLE]"
+  exit 2
+end
+
+intent_dir = File.expand_path(intent_dir_arg)
+
+fm = frontmatter_for(intent_dir)
+id = fm["id"].to_s.strip
+intent_name = fm["intent"].to_s.strip
+id = "(unknown)" if id.empty?
+intent_name = "(unknown)" if intent_name.empty?
+
+stage = current_stage(intent_dir)
+role_label = (role && !role.empty?) ? role : stage
+artifacts = Bridge.has_files(intent_dir)
+artifacts_str = artifacts.empty? ? "(none)" : artifacts.join(", ")
+
+lines = []
+lines << "=== Plastic agent report (synthesized) ==="
+lines << "Intent: #{id} - #{intent_name}"
+lines << "Stage: #{stage}"
+lines << "Role: #{role_label}"
+lines << "Status: synthesized (filesystem-derived; no agent-authored report)"
+lines << "Artifacts present: #{artifacts_str}"
+lines << "Checklist: #{checklist_progress(intent_dir)}"
+lines << "Outcome: #{outcome_line(intent_dir)}"
+lines << "Insights: #{insights_line(intent_dir)}"
+lines << "=== end report ==="
+
+puts lines.join("\n")

package/scripts/doctor.rb

@@ -17,6 +17,9 @@ require "digest"
 
 require_relative "lib/qmd_sync"
 require_relative "lib/intent_validator"
+require_relative "lib/graph_rebuild"
+require_relative "lib/links_projection"
+require_relative "lib/links_section"
 
 # Diagnostic engine, instantiable with an injected store/agent map so tests can
 # run it hermetically (no eval, no global-constant rewriting).
@@ -480,9 +483,178 @@ class Doctor
     # flagged: validate_graph does not compute it.
     checks.concat(graph_invariant_checks(intent_dirs))
 
+    # cross_store_resolution — RESOLVES (not just shape-checks) every cross-store
+    # `store:id` ref against the FULL store family via the relocation map
+    # (relocation consulted first), closing the shape-only gap i1/i3/i4 leave open.
+    # Resolution always spans all stores even under `--store` scoping; only the
+    # REPORTED findings are filtered to refs originating in the scoped store(s).
+    checks << cross_store_resolution_check(scopes: scopes)
+
+    # graph_links_projection — the `## Links` section of every intent must EQUAL its
+    # canonical I5 frontmatter projection (intent 72), in BOTH set membership AND
+    # ordering (sources first, then chain). Recomputes the projection from each
+    # intent's sources/chain + the on-disk basenames using the SAME resolver the
+    # scripts/project-links tool uses, so the two can never diverge. Resolution
+    # spans all stores; only the REPORTED findings are filtered to the scoped store.
+    checks << links_projection_check(scopes: scopes)
+
     checks
   end
 
+  # Build the cross-store node maps (basename + label per store) + relocation map
+  # from ALL stores, then for every intent compute its canonical `## Links`
+  # projection and flag any whose ACTUAL `## Links` section differs (membership or
+  # ordering drift), or whose projection raises UnresolvedRef. `scopes` (nil = full
+  # run) filters only the REPORTED findings by origin scope.
+  def links_projection_check(scopes: nil)
+    all_dirs = all_intent_dirs
+
+    store_index = Hash.new { |h, k| h[k] = [] }
+    node_index = Hash.new { |h, k| h[k] = {} }
+    intents = [] # { scope:, id:, sources:, chain:, path: }
+
+    all_dirs.each do |d|
+      md = File.join(d[:path], "#{d[:name]}.md")
+      next unless File.exist?(md)
+
+      fm = parse_frontmatter(md)
+      next unless fm.is_a?(Hash) && fm["id"]
+
+      id = fm["id"].to_s
+      store_index[d[:scope]] << id
+      node_index[d[:scope]][id] = { basename: d[:name], label: fm["intent"].to_s.strip }
+      intents << {
+        scope: d[:scope], id: id, path: md,
+        sources: Array(fm["sources"]).map(&:to_s),
+        chain: Array(fm["chain"]).map(&:to_s),
+      }
+    end
+
+    relocation_map = GraphRebuild.build_relocation_map(cross_store_index_texts)
+
+    findings = []
+    intents.each do |node|
+      next if scopes && !scopes.include?(node[:scope])
+
+      resolve = ->(ref) do
+        LinksProjection.resolve_ref_projection(
+          ref, referer_store: node[:scope],
+               relocation_map: relocation_map, store_index: store_index, node_index: node_index
+        )
+      end
+
+      begin
+        expected = LinksProjection.section(sources: node[:sources], chain: node[:chain], resolve: resolve)
+        actual = actual_links_section(node[:path])
+      rescue LinksProjection::UnresolvedRef => e
+        findings << "#{node[:id]} ## Links projection failed: #{e.message}"
+        next
+      rescue LinksSection::AmbiguousLinks => e
+        findings << "#{node[:id]} ## Links ambiguous: #{e.message}"
+        next
+      end
+
+      next if actual == expected
+
+      findings << "#{node[:id]} ## Links does not match its frontmatter projection (membership/ordering drift)"
+    end
+
+    graph_finding_check(
+      "graph_links_projection", findings,
+      "Every intent's ## Links equals its frontmatter projection (membership and ordering)",
+      "Run scripts/project-links to regenerate the canonical ## Links sections"
+    )
+  end
+
+  # Extract a file's ACTUAL REAL `## Links` section text (FENCE-AWARE), normalized
+  # to the canonical block shape the projection emits. Delegates to the shared
+  # LinksSection.extract_section so the doctor check and the project-links tool
+  # agree on the section location and never match a `## Links` heading inside an
+  # example code fence. Returns "" when the section is absent (which differs from
+  # any real projection, so a missing section is a finding).
+  def actual_links_section(path)
+    LinksSection.extract_section(IntentValidator.body_of(File.read(path)))
+  end
+
+  # Build the relocation map + cross-store store_index from ALL stores, then for
+  # every intent's cross-store `sources`/`chain` ref resolve it and flag:
+  #   - DEAD: the target resolves nowhere
+  #   - RELOCATED-STALE: the ref points at an old location the relocation log has
+  #     moved (the resolved location differs from the literal ref), e.g. the
+  #     `global:24` id-reuse hazard that direct resolution would silently accept.
+  # `scopes` (nil = full run) filters only the REPORTED findings by origin scope.
+  def cross_store_resolution_check(scopes: nil)
+    all_dirs = all_intent_dirs
+
+    # Per-scope node maps + store_index over the WHOLE family.
+    nodes_by_scope = Hash.new { |h, k| h[k] = {} }
+    store_index = Hash.new { |h, k| h[k] = [] }
+    all_dirs.each do |d|
+      md = File.join(d[:path], "#{d[:name]}.md")
+      next unless File.exist?(md)
+
+      fm = parse_frontmatter(md)
+      next unless fm.is_a?(Hash) && fm["id"]
+
+      id = fm["id"].to_s
+      store_index[d[:scope]] << id
+      nodes_by_scope[d[:scope]][id] = {
+        sources: Array(fm["sources"]).map(&:to_s),
+        chain: Array(fm["chain"]).map(&:to_s),
+      }
+    end
+
+    relocation_map = GraphRebuild.build_relocation_map(cross_store_index_texts)
+
+    findings = []
+    nodes_by_scope.each do |scope, nodes|
+      next if scopes && !scopes.include?(scope)
+
+      nodes.each do |id, edges|
+        %i[sources chain].each do |field|
+          edges[field].each do |ref|
+            next unless ref.include?(":") # only cross-store refs are resolved here
+
+            res = GraphRebuild.resolve_ref(ref, referer_store: scope,
+                                                relocation_map: relocation_map,
+                                                store_index: store_index)
+            case res[:status]
+            when :dead
+              findings << "#{id}.#{field} cross-store ref #{ref} resolves to no intent (dead)"
+            when :same_store
+              findings << "#{id}.#{field} cross-store ref #{ref} is relocated-stale (now same-store #{res[:id]})"
+            when :cross_store
+              findings << "#{id}.#{field} cross-store ref #{ref} is relocated-stale (now #{res[:ref]})" if res[:ref] != ref
+            end
+          end
+        end
+      end
+    end
+
+    graph_finding_check(
+      "graph_cross_store_resolution", findings,
+      "Every cross-store sources/chain ref resolves to a live, current intent",
+      "Run scripts/rebuild-graph to repoint/collapse/drop stale cross-store refs"
+    )
+  end
+
+  # { store_key => INDEX.md text } for every store (global + all projects), for the
+  # relocation-map builder. Reads INDEX.md one level above each store dir.
+  def cross_store_index_texts
+    texts = {}
+    global_index = File.join(plastic_home, "INDEX.md")
+    texts["global"] = File.read(global_index) if File.exist?(global_index)
+
+    projects_root = File.join(plastic_home, "projects")
+    if File.directory?(projects_root)
+      Dir.children(projects_root).each do |project|
+        idx = File.join(projects_root, project, "INDEX.md")
+        texts["project:#{project}"] = File.read(idx) if File.exist?(idx)
+      end
+    end
+    texts
+  end
+
   # Build a per-scope `nodes` map and surface IntentValidator.validate_graph
   # findings as warn-level checks. Scope-aware (the caller already filtered
   # `intent_dirs` by scope), so a `global` id is not falsely flagged as a dangler

package/scripts/hook-auto-arm

@@ -26,7 +26,7 @@ if triggered
 end
 
 # --- 2. Standing gate reminder when armed and pre-How ---
-bridge_data = Bridge.discover_bridge(session: ENV["CLAUDE_SESSION_ID"], cwd: Dir.pwd)
+bridge_data = Bridge.discover_bridge(session: ENV["CLAUDE_CODE_SESSION_ID"], cwd: Dir.pwd)
 if bridge_data && bridge_data.dig("build", "auto") == true
   intent = bridge_data["intent"] || {}
   store = intent["store"]; dir = intent["dir"]

package/scripts/hook-bash-gate

@@ -28,9 +28,9 @@ exit 0 if command.nil? || command.to_s.strip.empty?
 cwd = payload["cwd"]
 cwd = Dir.pwd if cwd.nil? || cwd.to_s.empty?
 
-# --- Load bridge (shared resolution; stdin session_id -> env -> /tmp scan) ---
+# --- Load bridge (shared resolution; stdin session_id -> CLAUDE_CODE_SESSION_ID -> /tmp scan) ---
 session = payload["session_id"]
-session = ENV["CLAUDE_SESSION_ID"] if session.nil? || session.to_s.empty?
+session = ENV["CLAUDE_CODE_SESSION_ID"] if session.nil? || session.to_s.empty?
 bridge_data = Bridge.discover_bridge(session: session, cwd: cwd)
 exit 0 unless bridge_data
 

package/scripts/hook-code-gate

@@ -3,24 +3,29 @@
 # frozen_string_literal: true
 
 # Usage: hook-code-gate <file_path>
-# PreToolUse gate (intent 27): when auto mode is armed and the active intent has not
-# reached How (plan.md + checklist.md), block edits to project code outside the store.
+# PreToolUse gate. Composes two independent block rules; EITHER blocks the edit:
+#   - Stage rule (intent 27): when auto mode is armed and the active intent has not
+#     reached How (plan.md + checklist.md), block edits to project code outside the store.
+#   - Worktree isolation rule (intent 73c2): when the intent has a provisioned code
+#     worktree, block project-code edits outside it; and block edits to another
+#     intent's store dir whose delivery lock is held by a live non-owner session.
 #
 # Exit 0 = allow. Exit 2 = block (reason on stderr, shown to the agent).
-# No bridge / auto not armed / How reached / path under ~/.plastic or the intent dir = allow.
+# No bridge = allow. Each rule fails open on its own conditions (see bridge.rb).
 
 require_relative "lib/bridge"
 
 file_path = ARGV[0]
 exit 0 unless file_path && !file_path.empty?
 
-session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_SESSION_ID"]
+session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_CODE_SESSION_ID"]
 
-# --- Load bridge (shared resolution; stdin session_id -> env -> /tmp scan) ---
+# --- Load bridge (shared resolution; stdin session_id -> CLAUDE_CODE_SESSION_ID -> /tmp scan) ---
 bridge_data = Bridge.discover_bridge(session: session, cwd: Dir.pwd)
 exit 0 unless bridge_data
 
-reason = Bridge.code_gate_decision(bridge_data, file_path)
+reason = Bridge.code_gate_decision(bridge_data, file_path) ||
+         Bridge.worktree_gate_decision(bridge_data, file_path, current_session: session)
 exit 0 unless reason
 
 $stderr.puts "PLASTIC GATE — #{reason}"

package/scripts/hook-create-gate

@@ -9,8 +9,8 @@
 # the on-disk file (which does not exist yet at PreToolUse), using IntentValidator
 # for born-complete frontmatter plus the sanctioned section structure.
 #
-# It depends ONLY on the stdin path + content, never on the auto-bridge or
-# CLAUDE_SESSION_ID, so it runs unconditionally (headless / background sessions).
+# It depends ONLY on the stdin path + content, never on the auto-bridge or any
+# session id, so it runs unconditionally (headless / background sessions).
 # It validates ONLY the intent file, never sentinel placeholder lifecycle files
 # (spec.md/plan.md/etc.); the path matcher excludes them.
 #

package/scripts/hook-gate-check

@@ -13,7 +13,7 @@ require_relative "lib/intent_validator"
 file_path = ARGV[0]
 exit 0 unless file_path && !file_path.empty?
 
-session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_SESSION_ID"]
+session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_CODE_SESSION_ID"]
 
 file_path_abs = File.expand_path(file_path)
 
@@ -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,136 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# PreToolUse retrieval gate (intent 84, Lever 2; operation-based redesign 89a).
+# Reads the tool call (JSON on stdin: tool_name + tool_input), computes
+# capabilities (QMD detect + freshness), 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).
+#
+# Only CONTENT SEARCH over store markdown is gated; reads and structural ops are
+# allowed. Code navigation is a soft prompt mandate (UserPromptSubmit power-tools),
+# not enforced here, so this hook no longer detects Serena.
+#
+# 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].
+  #   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] 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. 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 = 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/hook-session-start

@@ -48,7 +48,7 @@ bridge_data = nil
 if active.length == 1 && active.first =~ /store\/([\w-]+)\//
   dir_name = $1
   intent_dir = "#{store_root}/store/#{dir_name}"
-  session = ENV["CLAUDE_SESSION_ID"] || Process.pid.to_s
+  session = ENV["CLAUDE_CODE_SESSION_ID"] || Process.pid.to_s
   intent_id = dir_name.split("--").first
   intent_name = active.first[/\[([^\]]+)\]/, 1] || "unknown"
   bridge_data = Bridge.derive(session, intent_id: intent_id, intent_dir: intent_dir, store: store_root, name: intent_name)