@zalom/plastic 1.0.0-beta.1 → 1.0.0-beta.10

package/scripts/project-links

@@ -0,0 +1,287 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# project-links — project each intent's corrected sources/chain graph into its
+# canonical I5 `## Links` section, store-wide across the global, plastic, and
+# knowdb stores (intent 72). Deterministic and idempotent: a second run over a
+# projected store changes zero files. Touches ONLY the `## Links` section of each
+# intent file; frontmatter and every other section stay byte-identical.
+#
+# Usage:
+#   project-links [--plastic-home PATH] [--dry-run] [--audit-path PATH]
+#
+# Pure-Ruby (no bash). The pure logic lives in lib/links_projection.rb and
+# lib/links_section.rb; this shell does only discovery, IO, and reporting. It reads
+# frontmatter (it NEVER writes frontmatter, that is intent 49's domain) and the
+# on-disk `id--slug` directory basenames to build the cross-store resolver.
+# Never pushes ~/.plastic (no git ops here).
+
+require "time"
+require "fileutils"
+
+require_relative "lib/intent_validator"
+require_relative "lib/graph_rebuild"
+require_relative "lib/links_projection"
+require_relative "lib/links_section"
+
+class ProjectLinks
+  DEFAULT_HOME = File.join(Dir.home, ".plastic")
+
+  # The 72 intent dir audit destination (relative to plastic_home).
+  DEFAULT_AUDIT_REL =
+    "projects/plastic/store/72--links-graph-projection/resources/audit--links-projection.md"
+
+  def initialize(plastic_home: DEFAULT_HOME, dry_run: false, audit_path: nil)
+    @plastic_home = plastic_home
+    @dry_run = dry_run
+
+    # A dry run must NOT stomp the canonical audit (humans run --dry-run to review
+    # the plan). With no explicit --audit-path, a dry run writes a `.dry-run.md`
+    # sibling, leaving the canonical real-run audit untouched. An explicit
+    # --audit-path is always honored verbatim (tests inject it). Mirrors
+    # RebuildGraph's discipline exactly.
+    canonical = File.join(plastic_home, DEFAULT_AUDIT_REL)
+    @audit_path =
+      if audit_path
+        audit_path
+      elsif dry_run
+        canonical.sub(/\.md\z/, ".dry-run.md")
+      else
+        canonical
+      end
+  end
+
+  attr_reader :plastic_home, :dry_run, :audit_path
+
+  # The three in-scope stores, each as { key:, root:, store:, index: }.
+  def stores
+    list = []
+    global_store = File.join(plastic_home, "store")
+    if File.directory?(global_store)
+      list << { key: "global", root: plastic_home, store: global_store,
+                index: File.join(plastic_home, "INDEX.md") }
+    end
+
+    %w[plastic knowdb].each do |slug|
+      root = File.join(plastic_home, "projects", slug)
+      store = File.join(root, "store")
+      next unless File.directory?(store)
+
+      list << { key: "project:#{slug}", root: root, store: store,
+                index: File.join(root, "INDEX.md") }
+    end
+    list
+  end
+
+  # { id => { sources:, chain:, basename:, label:, path: } } for one store.
+  def load_nodes(store_dir)
+    nodes = {}
+    Dir.children(store_dir).reject { |e| e.start_with?(".") }.sort.each do |entry|
+      dir = File.join(store_dir, entry)
+      next unless File.directory?(dir)
+
+      md = File.join(dir, "#{entry}.md")
+      next unless File.exist?(md)
+
+      fm = IntentValidator.parse_frontmatter(md)
+      next unless fm.is_a?(Hash) && fm["id"]
+
+      nodes[fm["id"].to_s] = {
+        sources: Array(fm["sources"]).map(&:to_s),
+        chain: Array(fm["chain"]).map(&:to_s),
+        basename: entry, # the on-disk `id--slug` directory name
+        label: fm["intent"].to_s.strip,
+        path: md,
+      }
+    end
+    nodes
+  end
+
+  def run
+    store_list = stores
+    nodes_by_store = {}
+    index_texts = {}
+    store_index = {}
+    node_index = {}
+
+    store_list.each do |s|
+      key = s[:key]
+      nodes_by_store[key] = load_nodes(s[:store])
+      index_texts[key] = File.exist?(s[:index]) ? File.read(s[:index]) : ""
+      store_index[key] = nodes_by_store[key].keys
+      node_index[key] = nodes_by_store[key].transform_values do |v|
+        { basename: v[:basename], label: v[:label] }
+      end
+    end
+
+    relocation_map = GraphRebuild.build_relocation_map(index_texts)
+
+    results = {}
+    store_list.each do |s|
+      key = s[:key]
+      results[key] = project_store(
+        key, nodes_by_store[key],
+        relocation_map: relocation_map, store_index: store_index, node_index: node_index
+      )
+    end
+
+    emit_audit(store_list, results)
+    results
+  end
+
+  # Project every intent in ONE store. Returns
+  # { entries: [ {id:, status:, before:, after:, error:} ], counts: {...} }.
+  def project_store(referer_store, nodes, relocation_map:, store_index:, node_index:)
+    entries = []
+    nodes.each do |id, node|
+      resolve = ->(ref) do
+        LinksProjection.resolve_ref_projection(
+          ref, referer_store: referer_store,
+               relocation_map: relocation_map, store_index: store_index, node_index: node_index
+        )
+      end
+
+      content = File.read(node[:path])
+
+      begin
+        had_links = LinksSection.links_heading?(IntentValidator.body_of(content))
+        section_text = LinksProjection.section(
+          sources: node[:sources], chain: node[:chain], resolve: resolve
+        )
+        updated = LinksSection.rewrite(content, section_text)
+      rescue LinksProjection::UnresolvedRef, LinksSection::AmbiguousLinks => e
+        entries << { id: id, status: :failed, error: e.message }
+        next
+      end
+
+      if updated == content
+        entries << { id: id, status: :unchanged }
+        next
+      end
+
+      status = had_links ? :regenerated : :added
+      File.write(node[:path], updated) unless dry_run
+      entries << { id: id, status: status,
+                   before: extract_links(content), after: section_text }
+    end
+
+    counts = entries.each_with_object(Hash.new(0)) { |e, h| h[e[:status]] += 1 }
+    { entries: entries, counts: counts }
+  end
+
+  # Pull the current REAL `## Links` section text (fence-aware) from a file's
+  # content, for the audit sample. Returns "" when absent. Delegates to the shared
+  # LinksSection.extract_section so the audit, the rewriter, and the doctor check
+  # all agree on the section location (and never match a heading inside an example
+  # code fence).
+  def extract_links(content)
+    LinksSection.extract_section(IntentValidator.body_of(content))
+  rescue LinksSection::AmbiguousLinks
+    "(ambiguous: multiple ## Links headings)"
+  end
+
+  # Always write the audit (even in dry-run, so the human reviews the plan).
+  def emit_audit(store_list, results)
+    text = render_audit(store_list, results)
+    FileUtils.mkdir_p(File.dirname(audit_path))
+    File.write(audit_path, text)
+    text
+  end
+
+  STATUS_ORDER = %i[regenerated added unchanged failed].freeze
+  STATUS_LABELS = {
+    regenerated: "Regenerated (had a ## Links, content changed)",
+    added: "Added (no ## Links section, one inserted)",
+    unchanged: "Unchanged (already canonical)",
+    failed: "FAILED (resolver miss, NOT written)",
+  }.freeze
+
+  def render_audit(store_list, results)
+    lines = []
+    lines << "# Audit: store-wide ## Links projection (intent 72)"
+    lines << ""
+    lines << "Generated: #{Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")}#{dry_run ? " (DRY RUN)" : ""}"
+    lines << ""
+
+    total = STATUS_ORDER.to_h do |st|
+      [st, store_list.sum { |s| results[s[:key]][:counts][st] }]
+    end
+    lines << "Totals across all stores: " \
+             "regenerated #{total[:regenerated]}, added #{total[:added]}, " \
+             "unchanged #{total[:unchanged]}, failed #{total[:failed]}."
+    lines << ""
+
+    store_list.each do |s|
+      key = s[:key]
+      res = results[key]
+      counts = res[:counts]
+      lines << "## #{key}"
+      lines << ""
+      lines << "Regenerated #{counts[:regenerated]}, added #{counts[:added]}, " \
+               "unchanged #{counts[:unchanged]}, failed #{counts[:failed]}."
+      lines << ""
+
+      failed = res[:entries].select { |e| e[:status] == :failed }
+      unless failed.empty?
+        lines << "### FAILED (#{failed.size})"
+        failed.each { |e| lines << "- #{e[:id]}: #{e[:error]}" }
+        lines << ""
+      end
+
+      sample = res[:entries].select { |e| %i[regenerated added].include?(e[:status]) }.first(5)
+      next if sample.empty?
+
+      lines << "### Sample before/after (first #{sample.size})"
+      sample.each do |e|
+        lines << "- #{e[:id]} (#{e[:status]}):"
+        lines << "  - BEFORE:"
+        block_lines(e[:before]).each { |l| lines << "    #{l}" }
+        lines << "  - AFTER:"
+        block_lines(e[:after]).each { |l| lines << "    #{l}" }
+      end
+      lines << ""
+    end
+
+    lines.join("\n") + "\n"
+  end
+
+  def block_lines(text)
+    s = text.to_s.strip
+    return ["(none)"] if s.empty?
+
+    s.lines.map(&:rstrip)
+  end
+
+  # True iff any intent failed (resolver miss).
+  def any_failed?(results)
+    results.values.any? { |r| r[:counts][:failed].to_i.positive? }
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  home = ProjectLinks::DEFAULT_HOME
+  dry = false
+  audit = nil
+  i = 0
+  while i < ARGV.length
+    case ARGV[i]
+    when "--plastic-home" then home = ARGV[i + 1]; i += 2
+    when "--dry-run" then dry = true; i += 1
+    when "--audit-path" then audit = ARGV[i + 1]; i += 2
+    else i += 1
+    end
+  end
+
+  tool = ProjectLinks.new(plastic_home: home, dry_run: dry, audit_path: audit)
+  results = tool.run
+  totals = ProjectLinks::STATUS_ORDER.to_h do |st|
+    [st, results.values.sum { |r| r[:counts][st] }]
+  end
+  puts "project-links #{dry ? "DRY RUN" : "applied"}: " \
+       "regenerated #{totals[:regenerated]}, added #{totals[:added]}, " \
+       "unchanged #{totals[:unchanged]}, failed #{totals[:failed]} " \
+       "across #{results.size} store(s)."
+  puts "Audit: #{tool.audit_path}"
+  exit 1 if tool.any_failed?(results)
+end

package/scripts/qmd-sync

@@ -13,7 +13,10 @@
 #   qmd-sync register --store <dir>     # register one store as a collection
 #   qmd-sync register --all             # register the global store + all projects
 #   qmd-sync reindex --store <dir>      # update + embed that store's collection
+#   qmd-sync reindex --store <dir> --async  # same, detached/non-blocking
 #   qmd-sync status [--format json]     # read-only status
+#   qmd-sync search "<terms>" [--store <dir>] [--limit N] [--min-score F]
+#                                       # ranked store search; scope by --store or CWD
 #
 # --home <path> overrides the Plastic home (default: ~/.plastic).
 
@@ -71,8 +74,13 @@ when "register"
 when "reindex"
   dir = opt(ARGV, "--store") or (warn("reindex: pass --store <dir>"); exit 2)
   collection = QmdSync.collection_name(dir, plastic_home: home)
-  res = QmdSync.reindex(collection: collection)
-  puts "reindexed #{collection} (#{res[:ok] ? "ok" : "warn"})"
+  if ARGV.include?("--async")
+    QmdSync.reindex_async(collection: collection)
+    puts "reindex (async) #{collection} (started)"
+  else
+    res = QmdSync.reindex(collection: collection)
+    puts "reindexed #{collection} (#{res[:ok] ? "ok" : "warn"})"
+  end
   exit 0
 
 when "status"
@@ -86,7 +94,46 @@ when "status"
   end
   exit 0
 
+when "search"
+  # The query is the first bareword that is NOT the value of a known value-taking
+  # flag. Walk ARGV, skipping each such flag and the token right after it, then
+  # take the first remaining token that does not start with "--".
+  value_flags = %w[--store --limit --min-score --home]
+  query = nil
+  i = 0
+  while i < ARGV.length
+    tok = ARGV[i]
+    if value_flags.include?(tok)
+      i += 2
+      next
+    end
+    unless tok.start_with?("--")
+      query = tok
+      break
+    end
+    i += 1
+  end
+  collections =
+    if (dir = opt(ARGV, "--store"))
+      [QmdSync.collection_name(dir, plastic_home: home), "plastic-global"].uniq
+    else
+      QmdSync.collections_for_cwd(Dir.pwd, plastic_home: home)
+    end
+  limit = (opt(ARGV, "--limit") || "5").to_i
+  min_score = (opt(ARGV, "--min-score") || "0.5").to_f
+  hits = QmdSync.search(query, collections: collections, limit: limit, min_score: min_score)
+  if hits.empty?
+    puts "no qmd hits"
+  else
+    hits.each do |h|
+      pct = (h[:score] * 100).round
+      path = h[:file].to_s.sub(%r{\Aqmd://}, "")
+      puts "[#{pct}%] #{path} - #{h[:title]}"
+    end
+  end
+  exit 0
+
 else
-  warn "qmd-sync: unknown verb #{verb.inspect}. Use detect|register|reindex|status."
+  warn "qmd-sync: unknown verb #{verb.inspect}. Use detect|register|reindex|status|search."
   exit 2
 end

package/scripts/rebuild-graph

@@ -0,0 +1,244 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# rebuild-graph — repair the store-wide sources/chain frontmatter graph across the
+# global, plastic, and knowdb stores (intent 49). Deterministic, idempotent, and
+# one-directional (intent 68 I-invariants): dedupe, I3 (formative edge wins), I1
+# in-store backlinks, I2 preserved; cross-store refs resolved via a multi-hop
+# relocation map (relocation wins over coincidental id reuse). Emits a
+# before/after audit, then writes minimal style-preserving frontmatter.
+#
+# Usage:
+#   rebuild-graph [--plastic-home PATH] [--dry-run] [--audit-path PATH]
+#
+# Pure-Ruby (no bash). The pure logic lives in lib/graph_rebuild.rb and
+# lib/frontmatter_writer.rb; this shell does only discovery, IO, and reporting.
+# Never pushes ~/.plastic (no git ops here).
+
+require "yaml"
+require "date"
+require "time"
+require "fileutils"
+
+require_relative "lib/graph_rebuild"
+require_relative "lib/frontmatter_writer"
+require_relative "lib/intent_validator"
+
+class RebuildGraph
+  DEFAULT_HOME = File.join(Dir.home, ".plastic")
+
+  # The 49 intent dir audit destination (relative to plastic_home).
+  DEFAULT_AUDIT_REL =
+    "projects/plastic/store/49--store-wide-double-link-symmetry/resources/audit--graph-rebuild.md"
+
+  KIND_LABELS = {
+    dedupe: "Dedupes",
+    i3: "I3 resolutions (kept in sources, dropped from chain)",
+    repoint: "Cross-store repoints",
+    collapse: "Cross-store collapses (to bare same-store id)",
+    drop: "Dropped dead refs",
+    i1_backlink: "I1 backlinks added",
+  }.freeze
+
+  KIND_ORDER = %i[dedupe i3 repoint collapse drop i1_backlink].freeze
+
+  def initialize(plastic_home: DEFAULT_HOME, dry_run: false, audit_path: nil)
+    @plastic_home = plastic_home
+    @dry_run = dry_run
+
+    # A dry run must NOT stomp the canonical audit (the spec/checklist tell humans
+    # to run --dry-run to review the plan). When no explicit --audit-path is given,
+    # a dry run writes to a distinct `.dry-run.md` sibling, leaving the canonical
+    # real-run audit untouched. An explicit --audit-path is always honored verbatim
+    # (it is the caller's responsibility, and tests inject it).
+    canonical = File.join(plastic_home, DEFAULT_AUDIT_REL)
+    @audit_path =
+      if audit_path
+        audit_path
+      elsif dry_run
+        canonical.sub(/\.md\z/, ".dry-run.md")
+      else
+        canonical
+      end
+  end
+
+  attr_reader :plastic_home, :dry_run, :audit_path
+
+  # The three in-scope stores, each as { key:, root:, store:, index: }.
+  # `root` is the dir holding INDEX.md; `store` is the intents dir.
+  def stores
+    list = []
+    global_store = File.join(plastic_home, "store")
+    list << { key: "global", root: plastic_home, store: global_store,
+              index: File.join(plastic_home, "INDEX.md") } if File.directory?(global_store)
+
+    %w[plastic knowdb].each do |slug|
+      root = File.join(plastic_home, "projects", slug)
+      store = File.join(root, "store")
+      next unless File.directory?(store)
+
+      list << { key: "project:#{slug}", root: root, store: store,
+                index: File.join(root, "INDEX.md") }
+    end
+    list
+  end
+
+  # { id => { sources:, chain:, path: } } for one store.
+  def load_nodes(store_dir)
+    nodes = {}
+    Dir.children(store_dir).reject { |e| e.start_with?(".") }.sort.each do |entry|
+      dir = File.join(store_dir, entry)
+      next unless File.directory?(dir)
+
+      md = File.join(dir, "#{entry}.md")
+      next unless File.exist?(md)
+
+      fm = IntentValidator.parse_frontmatter(md)
+      next unless fm.is_a?(Hash) && fm["id"]
+
+      nodes[fm["id"].to_s] = {
+        sources: Array(fm["sources"]).map(&:to_s),
+        chain: Array(fm["chain"]).map(&:to_s),
+        path: md,
+      }
+    end
+    nodes
+  end
+
+  def run
+    store_list = stores
+    nodes_by_store = {}
+    index_texts = {}
+    store_index = {}
+
+    store_list.each do |s|
+      nodes_by_store[s[:key]] = load_nodes(s[:store])
+      index_texts[s[:key]] = File.exist?(s[:index]) ? File.read(s[:index]) : ""
+      store_index[s[:key]] = nodes_by_store[s[:key]].keys
+    end
+
+    relocation_map = GraphRebuild.build_relocation_map(index_texts)
+
+    results = {}
+    store_list.each do |s|
+      key = s[:key]
+      input = nodes_by_store[key].transform_values { |v| { sources: v[:sources], chain: v[:chain] } }
+      results[key] = GraphRebuild.rebuild_store(
+        input,
+        referer_store: key,
+        relocation_map: relocation_map,
+        store_index: store_index
+      )
+    end
+
+    write_back(store_list, nodes_by_store, results) unless dry_run
+    emit_audit(store_list, nodes_by_store, results)
+
+    results
+  end
+
+  # Write changed frontmatter back via the minimal style-preserving writer.
+  def write_back(store_list, nodes_by_store, results)
+    store_list.each do |s|
+      key = s[:key]
+      new_nodes = results[key][:nodes]
+      nodes_by_store[key].each do |id, original|
+        rebuilt = new_nodes[id]
+        next if rebuilt.nil?
+        next if rebuilt[:sources] == original[:sources] && rebuilt[:chain] == original[:chain]
+
+        content = File.read(original[:path])
+        updated = FrontmatterWriter.rewrite_arrays(content,
+                                                   sources: rebuilt[:sources],
+                                                   chain: rebuilt[:chain])
+        File.write(original[:path], updated) if updated != content
+      end
+    end
+  end
+
+  # Render the audit and write it (always, even in dry-run, so the human reviews
+  # the dry-run plan). Returns the rendered string.
+  def emit_audit(store_list, _nodes_by_store, results)
+    text = render_audit(store_list, results)
+    FileUtils.mkdir_p(File.dirname(audit_path))
+    File.write(audit_path, text)
+    text
+  end
+
+  # PURE-ish formatter (string from results). Per-store, grouped by kind.
+  def render_audit(store_list, results)
+    total = store_list.sum { |s| results[s[:key]][:changes].size }
+    lines = []
+    lines << "# Audit: store-wide sources/chain graph rebuild (intent 49)"
+    lines << ""
+    lines << "Generated: #{Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")}#{dry_run ? " (DRY RUN)" : ""}"
+    lines << ""
+    lines << "Total changes across all stores: #{total}"
+    lines << ""
+
+    store_list.each do |s|
+      key = s[:key]
+      changes = results[key][:changes]
+      lines << "## #{key}"
+      lines << ""
+      if changes.empty?
+        lines << "No changes."
+        lines << ""
+        next
+      end
+
+      KIND_ORDER.each do |kind|
+        group = changes.select { |c| c[:kind] == kind }
+        next if group.empty?
+
+        lines << "### #{KIND_LABELS[kind]} (#{group.size})"
+        group.each { |c| lines << "- #{format_change(c)}" }
+        lines << ""
+      end
+    end
+
+    lines.join("\n") + "\n"
+  end
+
+  def format_change(c)
+    case c[:kind]
+    when :dedupe
+      "#{c[:intent]}: sources #{c[:before][:sources].inspect} → #{c[:after][:sources].inspect}, " \
+        "chain #{c[:before][:chain].inspect} → #{c[:after][:chain].inspect}"
+    when :i3
+      "#{c[:intent]}: #{c[:before]} kept in sources, dropped from chain"
+    when :repoint
+      "#{c[:intent]}.#{c[:field]}: #{c[:before]} → #{c[:after]} (relocated cross-store)"
+    when :collapse
+      "#{c[:intent]}.#{c[:field]}: #{c[:before]} → #{c[:after]} (collapsed to bare same-store id)"
+    when :drop
+      "#{c[:intent]}.#{c[:field]}: #{c[:before]} dropped (resolves nowhere)"
+    when :i1_backlink
+      "#{c[:intent]}.chain += #{c[:backlink]} (formative backlink)"
+    else
+      c.inspect
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  home = RebuildGraph::DEFAULT_HOME
+  dry = false
+  audit = nil
+  i = 0
+  while i < ARGV.length
+    case ARGV[i]
+    when "--plastic-home" then home = ARGV[i + 1]; i += 2
+    when "--dry-run" then dry = true; i += 1
+    when "--audit-path" then audit = ARGV[i + 1]; i += 2
+    else i += 1
+    end
+  end
+
+  tool = RebuildGraph.new(plastic_home: home, dry_run: dry, audit_path: audit)
+  results = tool.run
+  total = results.values.sum { |r| r[:changes].size }
+  puts "rebuild-graph #{dry ? "DRY RUN" : "applied"}: #{total} change(s) across #{results.size} store(s)."
+  puts "Audit: #{tool.audit_path}"
+end

package/scripts/spawn-preamble

@@ -29,7 +29,22 @@ require_relative "lib/bridge"
 HONOR_INSTRUCTION =
   "You are operating inside Plastic. Use it as your operating scaffold. " \
   "Emit VALID lifecycle artifacts; do not hallucinate intents or stages. " \
-  "Your output is a deliverable, not a message."
+  "Your primary output is valid lifecycle artifacts; you close with a structured report about them."
+
+# Verbatim completion-report contract (intent 74). Kept as one constant so the
+# contract doc (skills/auto/references/agent-report-contract.md), the role prompts,
+# and the test assert against the exact same string. SINGLE SOURCE OF TRUTH for the
+# report wording: the work output is lifecycle artifacts, the final message is a
+# structured report about them. Both are required and they do not contradict.
+REPORT_CONTRACT =
+  "Before you finish, END your turn with a structured completion report as your " \
+  "FINAL MESSAGE (your return value), not a side-channel file. Do not go idle or " \
+  "finish silently. The report carries a common envelope: role, intent id, stage, " \
+  "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."
 
 def parse_args(argv)
   role = nil
@@ -116,6 +131,8 @@ lines << "Current stage: #{stage}"
 lines << "Cycle step / role: #{cycle}"
 lines << ""
 lines << HONOR_INSTRUCTION
+lines << ""
+lines << REPORT_CONTRACT
 lines << "=== end preamble ==="
 
 puts lines.join("\n")

package/skills/auto/SKILL.md

@@ -28,6 +28,13 @@ Work `dispatchable_queue` in `rank` order (these are `defer`/`research` disposit
 safe to deliver autonomously). Leave `human_only` and `next_big_thing` for the user — those
 are `drive`/`triage` items the human should lead. See the `plastic-dashboard` skill.
 
+QMD-first (when available): when the user describes the work to deliver rather than naming an
+intent, before scanning the store with grep/Read run
+`ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate, prior, or duplicate
+intents, then open the authoritative intent file for the hit you take over. The command is a no-op
+when QMD is absent, so fall back to the existing INDEX.md / file scan. (This is discovery; the
+reindex step under Completion is separate.)
+
 ## Arm the Lifecycle Gate (do this FIRST)
 
 Immediately after selecting the intent — before any other work — arm auto mode. This
@@ -68,6 +75,8 @@ Dispatch rule: sequential, one specialist per stage on one branch (the deliverab
 
 Spawn preamble (live-state injection): before dispatching any specialist, run `scripts/spawn-preamble <intent_dir> --role <role>` and PREPEND its output to that specialist's prompt. The preamble is a deterministic, filesystem-only snapshot of the active intent (id, intent line, current stage) plus the honoring instruction, so every spawned agent boots with accurate live state instead of guessing. This is the authoritative L2 mechanism for harnesses whose sub-agents do not inherit a top-level session event (see `docs/reference/harness-adapters.md`).
 
+Completion report (require-then-synthesize): every dispatched specialist MUST end with a structured completion report as its final message. The preamble's `REPORT_CONTRACT` injects this and the role prompts carry the per-role format (see `references/agent-report-contract.md`). Because child-agent honor is best-effort across harnesses, this is decision-shaping, not a hard block. When a specialist returns no usable report (it went idle, emitted only a bare ping, or its message was lost to a mid-run interjection), run `scripts/agent-report <intent_dir> --role <role>` to synthesize a deterministic filesystem-derived report so the handoff account always exists. Use the agent-authored report when present, the synthesized one otherwise.
+
 Final-gate review: dispatch an independent reviewer subagent at the final gate only, not as a standing role.
 
 Headless manual gate: when running headless or in the background, enforce gates manually and do not rely on hooks, because `CLAUDE_SESSION_ID` may be unset (this ties to the arm-gate fallback above).
@@ -184,11 +193,12 @@ During initial project creation, all decisions are non-destructive by definition
    - Update `chain` in the current intent's frontmatter
 6. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 7. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: deliver intent <ID> — <name>"`
-8. Refresh the QMD search index for this store (optional, no-op when QMD is absent):
+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:
    ```bash
-   ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>
+   ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async
    ```
-   Delivery is the lifecycle event that keeps the search index fresh. `<store-root>` is the
+   Completion is the lifecycle event that keeps the search index fresh. `<store-root>` is the
    store that holds this intent (the global store or the project store).
 9. Disarm the lifecycle gate (auto delivery is finished):
    ```bash