@zalom/plastic 1.0.0-alpha.26 → 1.0.0-alpha.28

package/package.json

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

package/scripts/doctor.rb

@@ -15,6 +15,8 @@ require "time"
 require "date"
 require "digest"
 
+require_relative "lib/qmd_sync"
+
 # Diagnostic engine, instantiable with an injected store/agent map so tests can
 # run it hermetically (no eval, no global-constant rewriting).
 class Doctor
@@ -1005,6 +1007,48 @@ class Doctor
     a_pre <=> b_pre
   end
 
+  # --- Check category: QMD integration (read-only, optional) ---
+  #
+  # QMD is an optional integration. When `qmd` is not on PATH we emit a single
+  # passing check and never fail — its absence is not a Plastic health problem.
+  # When present, we report whether every Plastic store is registered as a QMD
+  # collection. Everything here is read-only; we never invoke a mutating qmd
+  # subcommand. detector/runner are injectable so tests stay hermetic.
+  def check_qmd(detector: QmdSync.method(:detect), runner: QmdSync.default_runner)
+    return [absent_qmd_check] unless detector.call
+
+    checks = [check(
+      category: "qmd", name: "present", status: "pass",
+      message: "QMD installed"
+    )]
+
+    status = QmdSync.status(plastic_home: plastic_home, runner: runner, detector: detector)
+    missing = status[:missing] || []
+
+    if status[:all_registered]
+      checks << check(
+        category: "qmd", name: "collections", status: "pass",
+        message: "All #{status[:expected].size} Plastic store(s) registered as QMD collections"
+      )
+    else
+      checks << check(
+        category: "qmd", name: "collections", status: "warn",
+        message: "#{missing.size} Plastic store(s) not registered as QMD collections",
+        details: missing,
+        fixable: true, fix_hint: "Run: qmd-sync register --all"
+      )
+    end
+
+    checks
+  end
+
+  def absent_qmd_check
+    check(
+      category: "qmd", name: "present", status: "pass",
+      message: "QMD not installed (optional integration)"
+    )
+  end
+
   # --- Run all checks ---
 
   def run_checks(agent_key)
@@ -1015,6 +1059,7 @@ class Doctor
     all_checks += check_core_files(agent_key)
     all_checks += check_project_stores
     all_checks += check_deprecations
+    all_checks += check_qmd
 
     summarize(all_checks, agent_key)
   end

package/scripts/hook-session-start

@@ -8,6 +8,7 @@ require "date"
 require "yaml"
 require_relative "lib/bridge"
 require_relative "lib/boot_banner"
+require_relative "lib/qmd_sync"
 require_relative "doctor"
 
 index_path, store_root, mode, plugin_root = ARGV
@@ -204,6 +205,25 @@ parts = []
 parts << core_banner
 parts << ""
 
+# --- QMD search status (intent 45a, READ-ONLY) ---
+# Report-only line for the model (additionalContext), never systemMessage and
+# never the exit code. QmdSync.status shells out to `qmd collection list`, so the
+# whole block is guarded: a 2s timeout caps any hang, and rescue-all guarantees a
+# slow/broken/missing qmd appends nothing and the hook continues cleanly.
+begin
+  require "timeout"
+  qmd_status = Timeout.timeout(2) { QmdSync.status(plastic_home: store_root) }
+  if qmd_status[:present]
+    if qmd_status[:all_registered]
+      parts << "QMD: #{qmd_status[:registered].size} Plastic collections indexed (search with the qmd skill)."
+    else
+      parts << "QMD detected — run `qmd-sync register --all` to index your Plastic stores for search."
+    end
+  end
+rescue Exception
+  # Any failure (timeout, missing binary, parse error) — stay silent, never crash.
+end
+
 if plastic_md
   # Conventions always loaded first
   parts << plastic_md

package/scripts/lib/installer_core.rb

@@ -204,6 +204,8 @@ class InstallerCore
       "scripts/hook-auto-arm" => "scripts/hook-auto-arm",
       "scripts/lib/bridge.rb" => "scripts/lib/bridge.rb",
       "scripts/lib/boot_banner.rb" => "scripts/lib/boot_banner.rb",
+      "scripts/lib/qmd_sync.rb" => "scripts/lib/qmd_sync.rb",
+      "scripts/qmd-sync" => "scripts/qmd-sync",
       "scripts/lib/installer_core.rb" => "scripts/lib/installer_core.rb",
       "scripts/install.rb" => "scripts/install.rb",
       "scripts/update.rb" => "scripts/update.rb",

package/scripts/lib/qmd_sync.rb

@@ -0,0 +1,159 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+
+# QmdSync — the single place Plastic talks to QMD (intent 45a).
+#
+# Plastic computes only the Plastic-specific inputs (which store directory maps to
+# which `plastic-`prefixed collection, derived from projects.yml, plus a short
+# context description). The actual indexing is delegated to the `qmd` CLI; this
+# module never reimplements QMD's logic. QMD is optional: every public entry
+# no-ops cleanly when `qmd` is not on PATH.
+#
+# Pure and dependency-injected: all shelling-out goes through an injected
+# `runner` callable, so the whole module is unit-testable with no real binary,
+# no network, and no model downloads. The default runner shells out to `qmd`.
+module QmdSync
+  module_function
+
+  # A runner is `->(args_array) { [stdout_string, success_boolean] }`.
+  # The default invokes the real `qmd` binary.
+  def default_runner
+    lambda do |args|
+      require "open3"
+      out, _err, status = Open3.capture3("qmd", *args)
+      [out, status.success?]
+    end
+  end
+
+  # True when `qmd` is resolvable on PATH. The probe is injectable so tests do
+  # not depend on the host having qmd installed.
+  def detect(path_probe: method(:which_qmd))
+    !!path_probe.call
+  end
+
+  def which_qmd
+    ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
+      candidate = File.join(dir, "qmd")
+      File.file?(candidate) && File.executable?(candidate)
+    end
+  end
+
+  # Collection name for a store directory.
+  #   global store (<plastic_home>/store)        -> "plastic-global"
+  #   project store (<.../projects/<slug>/store) -> "plastic-<slug>"
+  # Slug is resolved from projects.yml by matching the project path; falls back
+  # to the directory's parent name when no registry match exists.
+  def collection_name(store_dir, plastic_home:)
+    store_dir = File.expand_path(store_dir)
+    global_store = File.expand_path(File.join(plastic_home, "store"))
+    return "plastic-global" if store_dir == global_store
+
+    slug = slug_for_store(store_dir, plastic_home: plastic_home)
+    "plastic-#{slug}"
+  end
+
+  # Every store Plastic knows about: the global store plus each registered
+  # project store. Returns [{collection:, dir:}, ...].
+  def enumerate_stores(plastic_home:)
+    stores = [{
+      collection: "plastic-global",
+      dir: File.expand_path(File.join(plastic_home, "store")),
+    }]
+
+    projects = load_projects(plastic_home)
+    projects.each do |slug, info|
+      path = info.is_a?(Hash) ? info["path"] : nil
+      next unless path
+      project_store = File.join(File.expand_path(path), "store")
+      # Project stores live under ~/.plastic/projects/<slug>/store as the mirror;
+      # registry `path` is the project code dir, so the tactical store is the
+      # plastic_home projects mirror.
+      mirror_store = File.expand_path(File.join(plastic_home, "projects", slug.to_s, "store"))
+      dir = Dir.exist?(mirror_store) ? mirror_store : project_store
+      stores << { collection: "plastic-#{slug}", dir: dir }
+    end
+    stores
+  end
+
+  # Register a store directory as a collection. Idempotent: re-running is safe.
+  # `qmd collection add` exits non-zero when the collection already exists, so we
+  # check the collection list first and treat an existing collection as success.
+  # No-op when qmd is absent. (`qmd context add` attaches a summary to a document
+  # path, not a collection-level description, so it is not used here.)
+  def register(collection:, dir:, runner: default_runner, detector: method(:detect))
+    return skip_result unless detector.call
+    return { ran: true, ok: true, output: "exists" } if list_collections(runner).include?(collection)
+    out, ok = runner.call(["collection", "add", dir, "--name", collection])
+    { ran: true, ok: ok, output: out.to_s.strip }
+  end
+
+  # Re-index a single collection: refresh the corpus then its embeddings.
+  # Scoped embed (-c) keeps delivery-time reindex fast. No-op when qmd absent.
+  def reindex(collection:, runner: default_runner, detector: method(:detect))
+    return skip_result unless detector.call
+    _o1, ok1 = runner.call(["update"])
+    _o2, ok2 = runner.call(["embed", "-c", collection])
+    { ran: true, ok: (ok1 && ok2) }
+  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))
+    return { present: false } unless detector.call
+
+    expected = enumerate_stores(plastic_home: plastic_home).map { |s| s[:collection] }
+    listed = list_collections(runner)
+    missing = expected - listed
+
+    { present: true, expected: expected, registered: listed,
+      missing: missing, all_registered: missing.empty? }
+  end
+
+  # --- internals ---
+
+  def skip_result
+    { ran: false, ok: true, skipped: true }
+  end
+
+  def list_collections(runner)
+    out, ok = runner.call(["collection", "list"])
+    return [] unless ok && out
+    # qmd prints lines like "plastic-global (qmd://plastic-global/)"; pull the
+    # leading collection token off each non-indented line.
+    out.lines.filter_map do |line|
+      next if line.start_with?(" ", "\t")
+      m = line.strip.match(/\A([A-Za-z0-9][\w.-]*)\b/)
+      m && m[1]
+    end.reject { |t| %w[Collections No].include?(t) }
+  end
+
+  def load_projects(plastic_home)
+    path = File.join(plastic_home, "projects.yml")
+    return {} unless File.exist?(path)
+    data = begin
+      YAML.safe_load(File.read(path)) || {}
+    rescue StandardError
+      {}
+    end
+    projects = data.is_a?(Hash) ? data["projects"] : nil
+    projects.is_a?(Hash) ? projects : {}
+  end
+
+  def slug_for_store(store_dir, plastic_home:)
+    projects = load_projects(plastic_home)
+    projects.each do |slug, info|
+      path = info.is_a?(Hash) ? info["path"] : nil
+      next unless path
+      project_root = File.expand_path(path)
+      mirror = File.expand_path(File.join(plastic_home, "projects", slug.to_s, "store"))
+      return slug.to_s if store_dir == File.join(project_root, "store") || store_dir == mirror
+    end
+    # Fallback: <...>/projects/<slug>/store -> slug, else parent dir name.
+    parts = store_dir.split(File::SEPARATOR)
+    idx = parts.rindex("projects")
+    return parts[idx + 1] if idx && parts[idx + 1] && parts[idx + 2] == "store"
+    File.basename(File.dirname(store_dir))
+  end
+end

package/scripts/qmd-sync

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# qmd-sync — deterministic CLI over QmdSync (intent 45a).
+#
+# Plastic skills and hooks call these verbs instead of assembling `qmd` commands
+# themselves. QMD is optional: when `qmd` is absent every verb exits 0 and prints
+# a skip notice, so callers can invoke unconditionally.
+#
+# Usage:
+#   qmd-sync detect                     # exit 0 if qmd present, 1 if absent
+#   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 status [--format json]     # read-only status
+#
+# --home <path> overrides the Plastic home (default: ~/.plastic).
+
+require "json"
+require_relative "lib/qmd_sync"
+
+def plastic_home(args)
+  if (i = args.index("--home")) && args[i + 1]
+    File.expand_path(args[i + 1])
+  else
+    File.expand_path(ENV["PLASTIC_HOME"] || "~/.plastic")
+  end
+end
+
+def opt(args, name)
+  (i = args.index(name)) && args[i + 1]
+end
+
+verb = ARGV.shift
+home = plastic_home(ARGV)
+
+unless QmdSync.detect
+  case verb
+  when "detect"
+    warn "QMD not detected on PATH."
+    exit 1
+  else
+    puts "QMD not detected; skipped (#{verb})."
+    exit 0
+  end
+end
+
+case verb
+when "detect"
+  puts "QMD detected."
+  exit 0
+
+when "register"
+  stores =
+    if ARGV.include?("--all")
+      QmdSync.enumerate_stores(plastic_home: home)
+    elsif (dir = opt(ARGV, "--store"))
+      [{ collection: QmdSync.collection_name(dir, plastic_home: home), dir: File.expand_path(dir) }]
+    else
+      warn "register: pass --store <dir> or --all"
+      exit 2
+    end
+  stores.each do |s|
+    next unless Dir.exist?(s[:dir])
+    res = QmdSync.register(collection: s[:collection], dir: s[:dir])
+    puts "registered #{s[:collection]} -> #{s[:dir]} (#{res[:ok] ? "ok" : "warn"})"
+  end
+  exit 0
+
+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"})"
+  exit 0
+
+when "status"
+  st = QmdSync.status(plastic_home: home)
+  if opt(ARGV, "--format") == "json"
+    puts JSON.generate(st)
+  else
+    puts "QMD present: #{st[:present]}"
+    puts "registered: #{Array(st[:registered]).join(", ")}"
+    puts "missing: #{Array(st[:missing]).join(", ")}" unless Array(st[:missing]).empty?
+  end
+  exit 0
+
+else
+  warn "qmd-sync: unknown verb #{verb.inspect}. Use detect|register|reindex|status."
+  exit 2
+end

package/skills/auto/SKILL.md

@@ -161,11 +161,17 @@ 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. Disarm the lifecycle gate (auto delivery is finished):
+8. Refresh the QMD search index for this store (optional, no-op when QMD is absent):
+   ```bash
+   ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>
+   ```
+   Delivery 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
    ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.disarm_auto(ENV["CLAUDE_SESSION_ID"])'
    ```
-9. Notify user: "Intent [ID] — [name] delivered. [1-2 sentence summary]. See outcome.md for details."
+10. Notify user: "Intent [ID] — [name] delivered. [1-2 sentence summary]. See outcome.md for details."
 
 ## Error Handling
 

package/skills/creating-project/SKILL.md

@@ -157,7 +157,18 @@ cd ~/.plastic && git add . && git commit -m "feat: spawn project <slug> from int
 cd <project> && git add . && git commit -m "feat: initialize project from intent <ID>"
 ```
 
-### 10. Announce
+### 10. Register the project store with QMD (optional)
+
+If QMD is installed, register the new project's store as a search collection:
+
+```bash
+ruby ~/.plastic/scripts/qmd-sync register --store ~/.plastic/projects/<slug>/store
+```
+
+`qmd-sync` no-ops when QMD is absent, so run it unconditionally. This adds the
+`plastic-<slug>` collection and indexes it.
+
+### 11. Announce
 
 Log in `## Insights` of each founding intent:
 > "Project `<slug>` created at `<path>`. Tactical mirror: `project-<slug>:1` (autonomous)"

package/skills/executing-plan/SKILL.md

@@ -75,6 +75,7 @@ Capture observations in `## Insights`. When ALL checklist items are checked:
 3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 4. Update cluster entries to show `_(completed)_`
 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> — <name>"`
+6. Refresh the QMD search index for this store (optional, no-op when QMD is absent): `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>`. Delivery is the lifecycle event that keeps the search index fresh.
 
 **This is NOT optional.** An intent with all checklist items done but no Outcome is a broken state. Complete the intent immediately — do not leave it for later.
 
@@ -100,6 +101,7 @@ Capture observations in `## Insights`. When ALL checklist items are checked:
 3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 4. Update cluster entries to show `_(completed)_`
 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> — <name>"`
+6. Refresh the QMD search index for this store (optional, no-op when QMD is absent): `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>`. Delivery is the lifecycle event that keeps the search index fresh.
 
 **This is NOT optional.** Complete the intent immediately when work is done.
 

package/skills/install/SKILL.md

@@ -153,7 +153,20 @@ Auto-commit the config change.
 Run `/plastic-doctor` and report the result. Resolve any fixable findings before
 announcing success.
 
-**Step 5: Announce**
+**Step 5: Register stores with QMD (optional)**
+
+QMD is an optional search layer. If it is installed, register the Plastic stores so
+they are searchable:
+
+```bash
+ruby ~/.plastic/scripts/qmd-sync detect && ruby ~/.plastic/scripts/qmd-sync register --all
+```
+
+`qmd-sync` no-ops cleanly when QMD is absent, so this is safe to run unconditionally.
+It registers `plastic-global` and every project store from `projects.yml`, then indexes
+them. Report what was registered, or that QMD was not detected and the step was skipped.
+
+**Step 6: Announce**
 
 > "Plastic installed globally at ~/.plastic/. Health check: [doctor summary].
 > Create your first intent with `/plastic-creating-intent`."