@zalom/plastic 1.0.0-alpha.34 → 1.0.0-alpha.36

package/agents/plastic-brainstorming.md

@@ -12,6 +12,8 @@ model: inherit
 
 You are the Plastic Brainstorming specialist. You own the Why-stage exploration of one intent in the What->Why->How->Exec cycle.
 
+When dispatched in auto mode you receive the standard Plastic spawn preamble (from `scripts/spawn-preamble`) prepended to your prompt: it states the active intent id, intent line, current stage, your role, and the instruction to emit valid lifecycle artifacts. Honor it as your live state; do not re-derive or contradict it.
+
 ## Your Responsibilities
 
 1. **Explore the problem** — read the intent's `## Intent` and `## Context`, the linked intents, and the relevant code

package/agents/plastic-executor.md

@@ -12,6 +12,8 @@ model: inherit
 
 You are the Plastic Executor. You own the Exec stage of the What->Why->How->Exec cycle.
 
+When dispatched in auto mode you receive the standard Plastic spawn preamble (from `scripts/spawn-preamble`) prepended to your prompt: it states the active intent id, intent line, current stage, your role, and the instruction to emit valid lifecycle artifacts. Honor it as your live state; do not re-derive or contradict it.
+
 ## Your Responsibilities
 
 1. **Implement the actions** — make the code changes for each action in order

package/agents/plastic-planner.md

@@ -12,6 +12,8 @@ model: inherit
 
 You are the Plastic Planner. You own the How stage of the What->Why->How->Exec cycle.
 
+When dispatched in auto mode you receive the standard Plastic spawn preamble (from `scripts/spawn-preamble`) prepended to your prompt: it states the active intent id, intent line, current stage, your role, and the instruction to emit valid lifecycle artifacts. Honor it as your live state; do not re-derive or contradict it.
+
 ## Your Responsibilities
 
 1. **Decompose the spec** — break the approach into ordered, independent actions

package/agents/plastic-spec-specialist.md

@@ -12,6 +12,8 @@ model: inherit
 
 You are the Plastic Spec Specialist. You own the Why-to-How boundary in the What->Why->How->Exec cycle.
 
+When dispatched in auto mode you receive the standard Plastic spawn preamble (from `scripts/spawn-preamble`) prepended to your prompt: it states the active intent id, intent line, current stage, your role, and the instruction to emit valid lifecycle artifacts. Honor it as your live state; do not re-derive or contradict it.
+
 ## Your Responsibilities
 
 1. **Consolidate the Why** — turn the enriched `## Context` and `### Decisions` into one spec

package/hooks/hooks.json

@@ -93,6 +93,16 @@
             "statusMessage": "Checking auto mode..."
           }
         ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" qmd-search",
+            "statusMessage": "Searching QMD..."
+          }
+        ]
       }
     ]
   }

package/hooks/qmd-search

@@ -0,0 +1,8 @@
+#!/bin/bash
+# qmd-first search hook launcher (intent 66). No-op when there is no global store.
+GLOBAL_INDEX="$HOME/.plastic/INDEX.md"
+if [ ! -f "$GLOBAL_INDEX" ]; then
+  exit 0
+fi
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec ruby "$SCRIPT_DIR/../scripts/hook-qmd-search" "$HOME/.plastic"

package/package.json

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

package/scripts/doctor.rb

@@ -42,6 +42,7 @@ class Doctor
     plastic-gate-check
     plastic-continue
     plastic-future-intent-check
+    plastic-qmd-search
   ].freeze
 
   CLAUDE_HOOK_EVENTS = %w[SessionStart PreCompact PostToolUse UserPromptSubmit].freeze

package/scripts/hook-gate-check

@@ -8,6 +8,7 @@
 
 require "json"
 require_relative "lib/bridge"
+require_relative "lib/intent_validator"
 
 file_path = ARGV[0]
 exit 0 unless file_path && !file_path.empty?
@@ -28,6 +29,24 @@ if intent_dir_abs
   end
 end
 
+# --- Artifact-validity backstop (intent 4a1c1) ---
+# When the written file IS the intent file itself (the `<id>--<slug>.md` directly
+# inside `store/<id>--<slug>/`), run IntentValidator on it. This is headless-safe:
+# it depends only on the file path and disk, never on a bridge or session. In the
+# PostToolUse model the write has already happened, so we cannot prevent it; the
+# loud non-zero exit + stderr is the rejection signal. NOT for spec.md/plan.md/
+# checklist.md/outcome.md/savepoint.md — those are validated by the stage gates.
+if intent_dir_abs && File.basename(file_path_abs) == File.basename(Bridge.intent_file(intent_dir_abs))
+  result = IntentValidator.validate(intent_dir_abs)
+  unless result[:ok]
+    warn "PLASTIC ARTIFACT INVALID — #{File.basename(file_path_abs)} is not born complete:"
+    result[:missing].each { |field| warn "  missing required field: #{field}" }
+    result[:errors].each { |error| warn "  #{error}" }
+    warn "Fix the frontmatter; the intent is not valid until every required field is present and sources/chain are well-formed."
+    exit 1
+  end
+end
+
 # --- Find bridge file ---
 bridge_data = Bridge.discover_bridge(session: session, cwd: Dir.pwd)
 

package/scripts/hook-qmd-search

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# qmd-first UserPromptSubmit hook (intent 66). Reads the prompt from stdin JSON,
+# delegates the decision to QmdHook.run under a hard timeout, and prints
+# hookSpecificOutput when there is something to inject/remind. Silent no-op (exit
+# 0) when qmd is absent, the prompt is trivial, or anything goes wrong. ARGV[0]
+# is the plastic_home (passed by the launcher); defaults to ~/.plastic.
+require "json"
+require "timeout"
+require_relative "lib/qmd_hook"
+
+raw = begin
+  STDIN.read
+rescue StandardError
+  ""
+end
+
+prompt = begin
+  parsed = JSON.parse(raw)
+  parsed.is_a?(Hash) ? parsed["user_prompt"].to_s : ""
+rescue StandardError
+  ""
+end
+
+plastic_home = (ARGV[0] && !ARGV[0].empty?) ? ARGV[0] : File.expand_path("~/.plastic")
+
+context = begin
+  Timeout.timeout(2) do
+    QmdHook.run(prompt: prompt, cwd: Dir.pwd, plastic_home: plastic_home)
+  end
+rescue Exception
+  nil
+end
+
+exit 0 if context.nil? || context.strip.empty?
+
+puts JSON.generate(
+  "hookSpecificOutput" => {
+    "hookEventName" => "UserPromptSubmit",
+    "additionalContext" => context,
+  }
+)

package/scripts/lib/installer_core.rb

@@ -199,6 +199,8 @@ 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-qmd-search" => "scripts/hook-qmd-search",
+      "scripts/lib/qmd_hook.rb" => "scripts/lib/qmd_hook.rb",
       "scripts/hook-code-gate" => "scripts/hook-code-gate",
       "scripts/hook-bash-gate" => "scripts/hook-bash-gate",
       "scripts/hook-auto-arm" => "scripts/hook-auto-arm",
@@ -208,6 +210,7 @@ class InstallerCore
       "scripts/qmd-sync" => "scripts/qmd-sync",
       "scripts/lib/intent_validator.rb" => "scripts/lib/intent_validator.rb",
       "scripts/validate-intent" => "scripts/validate-intent",
+      "scripts/spawn-preamble" => "scripts/spawn-preamble",
       "scripts/lib/store_provisioning.rb" => "scripts/lib/store_provisioning.rb",
       "scripts/provision-project-store" => "scripts/provision-project-store",
       "scripts/lib/installer_core.rb" => "scripts/lib/installer_core.rb",
@@ -542,6 +545,7 @@ class InstallerCore
           { "type" => "command", "command" => "#{hook_dir}/plastic-continue", "statusMessage" => "Checking for continue..." },
           { "type" => "command", "command" => "#{hook_dir}/plastic-future-intent-check", "statusMessage" => "Checking future intents..." },
           { "type" => "command", "command" => "#{hook_dir}/plastic-auto-arm", "statusMessage" => "Checking auto mode..." },
+          { "type" => "command", "command" => "#{hook_dir}/plastic-qmd-search", "statusMessage" => "Searching QMD..." },
         ],
       },
     }

package/scripts/lib/qmd_hook.rb

@@ -0,0 +1,44 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "qmd_sync"
+
+# QmdHook — decision logic for the qmd-first UserPromptSubmit hook (intent 66).
+# Pure and dependency-injected: returns the additionalContext string to emit, or
+# nil to emit nothing. The executable hook wires real deps and prints; this is
+# unit-tested with a fake runner/detector (no real qmd, no network).
+module QmdHook
+  module_function
+
+  MIN_PROMPT_LENGTH = 10
+  REMINDER = "qmd is available: query it (`qmd search` / `qmd query` over the " \
+             "`plastic-*` collections) before grep/Read when gathering intent " \
+             "context (sources/chain) or checking whether this work already " \
+             "exists as an intent."
+
+  def run(prompt:, cwd:, plastic_home:, runner: QmdSync.default_runner,
+          detector: QmdSync.method(:detect), limit: 3, min_score: 0.5)
+    return nil unless detector.call
+    p = prompt.to_s.strip
+    return nil if p.length < MIN_PROMPT_LENGTH
+    return nil if p.downcase == "continue"
+
+    collections = QmdSync.collections_for_cwd(cwd, plastic_home: plastic_home)
+    hits = QmdSync.search(p, collections: collections, limit: limit,
+                          min_score: min_score, runner: runner, detector: detector)
+
+    parts = []
+    if hits.any?
+      parts << "Related / prior Plastic intents (qmd BM25, includes completed) — " \
+               "check before treating this as new work:"
+      hits.each do |h|
+        loc = h[:file].to_s.sub(%r{\Aqmd://}, "")
+        pct = (h[:score] * 100).round
+        parts << "- [#{pct}%] #{loc} — #{h[:title]}"
+      end
+      parts << ""
+    end
+    parts << REMINDER
+    parts.join("\n")
+  end
+end

package/scripts/lib/qmd_sync.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "yaml"
+require "json"
 
 # QmdSync — the single place Plastic talks to QMD (intent 45a).
 #
@@ -111,6 +112,55 @@ module QmdSync
       missing: missing, all_registered: missing.empty? }
   end
 
+  # Read-only BM25 search over one or more collections. Returns hits sorted by
+  # score (desc), filtered by min_score, capped at limit:
+  #   [{ score: Float, file: String, line: Integer|nil, title: String, snippet: String }, ...]
+  # No-ops to [] when qmd is absent or the query is blank. Uses `qmd search --json`
+  # (BM25, no embeddings / no model downloads). Pure via the injected runner.
+  def search(query, collections:, limit: 3, min_score: 0.5, runner: default_runner, detector: method(:detect))
+    return [] unless detector.call
+    q = query.to_s.strip
+    return [] if q.empty? || Array(collections).empty?
+
+    args = ["search", q]
+    Array(collections).each { |c| args.concat(["-c", c]) }
+    args << "--json"
+
+    out, ok = runner.call(args)
+    return [] unless ok && out && !out.strip.empty?
+
+    parsed = begin
+      JSON.parse(out)
+    rescue StandardError
+      return []
+    end
+    return [] unless parsed.is_a?(Array)
+
+    parsed.filter_map do |h|
+      next unless h.is_a?(Hash)
+      score = h["score"].to_f
+      next if score < min_score
+      { score: score, file: h["file"].to_s, line: h["line"],
+        title: h["title"].to_s, snippet: h["snippet"].to_s }
+    end.sort_by { |h| -h[:score] }.first(limit)
+  end
+
+  # Which collections to search for a given working directory: the matched
+  # project's collection plus plastic-global, or just plastic-global when the
+  # CWD is not inside any registered project. Project match = CWD equals the
+  # registered path or is nested under it.
+  def collections_for_cwd(cwd, plastic_home:)
+    cwd = File.expand_path(cwd)
+    projects = load_projects(plastic_home)
+    slug, = projects.find do |_s, info|
+      path = info.is_a?(Hash) ? info["path"] : nil
+      next false unless path
+      root = File.expand_path(path)
+      cwd == root || cwd.start_with?(root + File::SEPARATOR)
+    end
+    slug ? ["plastic-#{slug}", "plastic-global"] : ["plastic-global"]
+  end
+
   # --- internals ---
 
   def skip_result

package/scripts/spawn-preamble

@@ -0,0 +1,121 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# spawn-preamble — deterministic live-state injection for spawned agents
+# (intent 4a1c1, agent harness foundation).
+#
+# Emits a preamble block built ONLY from filesystem state for a single intent
+# directory. 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. This is the authoritative L2 (live-state) mechanism for harnesses whose
+# spawned sub-agents do not inherit a top-level session event (see
+# docs/reference/harness-adapters.md).
+#
+# Usage:
+#   spawn-preamble <intent_dir> [--role ROLE] [--step STEP]
+#
+# The preamble reports the active intent (id + intent line from frontmatter), the
+# current lifecycle stage (last savepoint line if present, else derived from which
+# lifecycle files exist), the cycle role/step (from --role/--step, else the
+# derived stage), and an imperative honoring instruction.
+#
+# Exit codes: 0 (preamble emitted), 2 (usage).
+
+require_relative "lib/bridge"
+
+# Verbatim honoring instruction. Kept as one constant so the contract doc and the
+# test assert against the exact same string.
+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."
+
+def parse_args(argv)
+  role = nil
+  step = nil
+  positional = []
+  i = 0
+  while i < argv.length
+    case argv[i]
+    when "--role"
+      role = argv[i + 1]
+      i += 2
+    when "--step"
+      step = argv[i + 1]
+      i += 2
+    else
+      positional << argv[i]
+      i += 1
+    end
+  end
+  [positional.first, role, step]
+end
+
+# Read the intent file frontmatter via the same parser the validator uses, so the
+# id/intent we report match what the rest of Plastic sees. Returns a Hash (possibly
+# empty) — 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 label. Prefer the last non-empty line of savepoint.md (the ledger
+# already encodes the furthest-reached milestone). Fall back to the file-derived
+# stage when there is no ledger.
+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
+
+intent_dir_arg, role, step = parse_args(ARGV)
+
+if intent_dir_arg.nil? || intent_dir_arg.empty?
+  warn "usage: spawn-preamble <intent_dir> [--role ROLE] [--step STEP]"
+  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)
+cycle = role || step || stage
+
+lines = []
+lines << "=== Plastic spawn preamble ==="
+lines << "Store: #{intent_dir}"
+lines << "Active intent: #{id} - #{intent_name}"
+lines << "Current stage: #{stage}"
+lines << "Cycle step / role: #{cycle}"
+lines << ""
+lines << HONOR_INSTRUCTION
+lines << "=== end preamble ==="
+
+puts lines.join("\n")

package/skills/auto/SKILL.md

@@ -66,6 +66,8 @@ Roster (one role per cycle stage):
 
 Dispatch rule: sequential, one specialist per stage on one branch (the deliverables share files). Gate each deliverable against the stage's exit criteria before handing off. The How and Exec phases below default to Plastic's native dispatch (`plastic-executing-plan`) and delegate to the superpowers skills only when they are available or the user asks; do not restate the phase mechanics here.
 
+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`).
+
 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).

package/skills/auto/references/agent-architecture.md

@@ -48,6 +48,19 @@ The chain: intent `## Intent` / `## Context`, then enriched `## Context` plus
 `### Decisions`, then `spec.md`, then `plan.md` plus `actions/` plus `checklist.md`,
 then the code changes plus a checked-off checklist plus `## Insights`.
 
+### Spawn Preamble (L2 live-state injection)
+
+Every dispatched specialist is booted with a spawn preamble: the enforcer runs
+`scripts/spawn-preamble <intent_dir> --role <role>` and prepends its output to the
+specialist's prompt. The preamble is a pure function of the intent directory on disk
+(no network, no clock, no randomness), so it is deterministic and rebuildable. It
+carries the active intent id and intent line, the current lifecycle stage (the last
+savepoint line, else stage derived from which lifecycle files exist), the cycle
+role, and the honoring instruction that the agent must emit valid lifecycle artifacts
+and not hallucinate intents or stages. This is the standard L2 live-state mechanism
+for harnesses whose spawned sub-agents do not inherit the top-level session event. See
+`docs/reference/harness-adapters.md` for how it slots into the per-harness contract.
+
 ### Gate Ownership
 
 The enforcer arms and verifies the lifecycle gate, then gates every stage transition.