@zalom/plastic 1.0.0-alpha.9 → 1.0.0-beta.2

package/scripts/lib/intent_validator.rb

@@ -0,0 +1,235 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+require "date"
+require "time"
+
+# IntentValidator — the single source of truth for "is an intent born complete?"
+# (intent 60).
+#
+# An intent is born complete when its frontmatter carries every required field
+# and its `sources` and `chain` are well-formed arrays of Folgezettel id references
+# (bare ids like `1a2`, or cross-store refs like `global:1a2`; integer ids are coerced).
+# This module is the only definition of that contract; the `validate-intent` CLI,
+# the doctor diagnostics, and the creating-intent skill all consult it so the
+# definition never drifts across copies.
+#
+# Pure and dependency-injected: `validate` accepts an injectable `plastic_home`
+# for house-style parity, parses with a rescue-to-safe-default reader, uses no
+# `eval`, and performs no file writes and no global-constant injection.
+module IntentValidator
+  module_function
+
+  # Must match Doctor::REQUIRED_FRONTMATTER_FIELDS (scripts/doctor.rb).
+  REQUIRED_FIELDS = %w[id intent sources chain created author tags].freeze
+
+  # Fields whose value must be a well-formed array of valid id strings.
+  ARRAY_ID_FIELDS = %w[sources chain].freeze
+
+  # Sanctioned top-level intent sections, in order (intent 60b). The only
+  # sanctioned `###` subsection is `### Decisions`, which is OPTIONAL (added after
+  # brainstorming) and therefore never flagged as missing. This is the single
+  # definition shared by the create gate, the validate-intent CLI, and doctor.
+  SANCTIONED_SECTIONS = ["## Intent", "## Context", "## Outcome", "## Insights", "## Links"].freeze
+
+  # Folgezettel id form: digits then an optional lowercase-letter/digit suffix
+  # (for example "14", "14a", "4a1"). Mirrors scripts/folgezettel-id.
+  ID_PATTERN = /\A([a-z0-9-]+:)?\d+[a-z0-9]*\z/
+
+  # True iff `value` is a String matching the Folgezettel id form.
+  def valid_id?(value)
+    value.to_s.match?(ID_PATTERN)
+  end
+
+  # Read a file's YAML frontmatter, returning the parsed Hash (or {} when the
+  # frontmatter block is empty), or nil when there is no parseable frontmatter.
+  # A copy of Doctor#parse_frontmatter so `created:` dates do not crash.
+  def parse_frontmatter(path)
+    return nil unless File.exist?(path)
+
+    parse_frontmatter_text(File.read(path))
+  rescue StandardError
+    nil
+  end
+
+  # PURE: parse YAML frontmatter from a content STRING (no file IO). Returns the
+  # parsed Hash, {} for an empty block, or nil when there is no parseable block.
+  def parse_frontmatter_text(content)
+    return nil unless content.is_a?(String) && content.start_with?("---")
+
+    parts = content.split("---", 3)
+    return nil if parts.length < 3
+
+    YAML.safe_load(parts[1], permitted_classes: [Date, Time]) || {}
+  rescue StandardError
+    nil
+  end
+
+  # PURE: strip the leading YAML frontmatter block from a content STRING,
+  # returning the body text (everything after the closing `---`). When there is
+  # no frontmatter block, the whole content is the body.
+  def body_of(content)
+    return "" unless content.is_a?(String)
+    return content unless content.start_with?("---")
+
+    parts = content.split("---", 3)
+    parts.length < 3 ? content : parts[2]
+  end
+
+  # PURE: given the intent file body text, return sanctioned-section findings.
+  # Flags any unknown top-level `## ` heading and any missing sanctioned section.
+  # Ignores `### ` subsections entirely (Decisions is optional and lives under
+  # Context). Returns { ok:, missing: [section names], unknown: [heading strings] }.
+  def validate_sections(body)
+    headings = body.to_s.lines.filter_map do |l|
+      s = l.strip
+      s if s.start_with?("## ") && !s.start_with?("### ")
+    end
+    present = headings & SANCTIONED_SECTIONS
+    missing = SANCTIONED_SECTIONS - present
+    unknown = headings - SANCTIONED_SECTIONS
+    { ok: missing.empty? && unknown.empty?, missing: missing, unknown: unknown }
+  end
+
+  # PURE: given a parsed frontmatter Hash (or nil), return
+  # { ok: Boolean, missing: [field names], errors: [human strings] }.
+  def validate_frontmatter(fm)
+    unless fm.is_a?(Hash)
+      return { ok: false, missing: REQUIRED_FIELDS.dup, errors: ["no frontmatter found"] }
+    end
+
+    missing = REQUIRED_FIELDS.reject { |f| fm.key?(f) }
+    errors = missing.map { |f| "missing required field: #{f}" }
+
+    ARRAY_ID_FIELDS.each do |key|
+      next unless fm.key?(key)
+
+      value = fm[key]
+      unless value.is_a?(Array)
+        errors << "#{key} must be an array"
+        next
+      end
+
+      value.each do |element|
+        errors << "#{key} has invalid id: #{element.inspect}" unless valid_id?(element)
+      end
+    end
+
+    { ok: missing.empty? && errors.empty?, missing: missing, errors: errors }
+  end
+
+  # PURE: combine the frontmatter result with section-structure findings for a
+  # content STRING. Returns the frontmatter result hash extended with
+  # :section_missing, :section_unknown, and folded section errors; :ok is the AND
+  # of frontmatter and sections. Lets the create gate validate proposed content
+  # (no file on disk) with the same definition as the CLI and doctor.
+  def validate_content(content)
+    fm_result = validate_frontmatter(parse_frontmatter_text(content))
+    sections = validate_sections(body_of(content))
+    merge_sections(fm_result, sections)
+  end
+
+  # Fold section findings into a frontmatter result hash (shared by validate and
+  # validate_content). Does not mutate the input.
+  def merge_sections(fm_result, sections)
+    errors = fm_result[:errors].dup
+    sections[:unknown].each { |h| errors << "unknown section: #{h}" }
+    sections[:missing].each { |s| errors << "missing required section: #{s}" }
+    {
+      ok: fm_result[:ok] && sections[:ok],
+      missing: fm_result[:missing],
+      errors: errors,
+      section_missing: sections[:missing],
+      section_unknown: sections[:unknown],
+    }
+  end
+
+  # Resolve an intent directory's primary md file and validate its frontmatter
+  # AND its sanctioned section structure. `plastic_home` is accepted for
+  # house-style parity (injectable) even though validation reads the dir directly.
+  def validate(intent_dir, plastic_home: File.join(Dir.home, ".plastic"))
+    md_path = File.join(intent_dir, "#{File.basename(intent_dir)}.md")
+    content = File.exist?(md_path) ? File.read(md_path) : nil
+    validate_content(content)
+  end
+
+  # PURE: cross-intent graph-shape invariants (intent 68). These need visibility
+  # over the whole intent set, so they live apart from the single-file born-complete
+  # helpers above (which must not drift). No file IO: the caller builds `nodes`.
+  #
+  # `nodes` is a Hash { id(String) => { sources: [ids], chain: [ids] } } for every
+  # intent in ONE store's id space. Returns { i1: [...], i3: [...], i4: [...] },
+  # each an array of human-readable finding strings.
+  #
+  # I2 (no false symmetry) is INTENTIONALLY not computed: a relational `chain` entry
+  # with no reciprocal `sources` is valid and must never be flagged.
+  def validate_graph(nodes)
+    nodes = normalize_nodes(nodes)
+    { i1: graph_i1(nodes), i3: graph_i3(nodes), i4: graph_i4(nodes) }
+  end
+
+  # Coerce node arrays to deduped String id lists; tolerate missing keys.
+  def normalize_nodes(nodes)
+    return {} unless nodes.is_a?(Hash)
+
+    nodes.each_with_object({}) do |(id, edges), acc|
+      edges = {} unless edges.is_a?(Hash)
+      acc[id.to_s] = {
+        sources: Array(edges[:sources] || edges["sources"]).map(&:to_s).uniq,
+        chain: Array(edges[:chain] || edges["chain"]).map(&:to_s).uniq,
+      }
+    end
+  end
+
+  # An id is a cross-store reference (out of this store's scope) when it carries a
+  # `<store>:` prefix, mirroring how `valid_id?` accepts the prefix. Such refs are
+  # resolved outside this node set, so they are never danglers here.
+  def cross_store_ref?(id)
+    id.to_s.include?(":")
+  end
+
+  # I1 (formative reciprocity): for every B and every `s` in B.sources that resolves
+  # in this store, B must appear in s.chain. A `s` that does not resolve is an I4
+  # dangler, not an I1 violation, so it is skipped here.
+  def graph_i1(nodes)
+    findings = []
+    nodes.each do |b_id, edges|
+      edges[:sources].each do |s|
+        next if cross_store_ref?(s)
+        next unless nodes.key?(s)
+
+        findings << "#{b_id}.sources lists #{s} but #{s}.chain is missing #{b_id}" unless nodes[s][:chain].include?(b_id)
+      end
+    end
+    findings
+  end
+
+  # I3 (per-node disjoint): X.sources and X.chain must not overlap.
+  def graph_i3(nodes)
+    findings = []
+    nodes.each do |x_id, edges|
+      (edges[:sources] & edges[:chain]).each do |overlap|
+        findings << "#{x_id} lists #{overlap} in BOTH sources and chain"
+      end
+    end
+    findings
+  end
+
+  # I4 (no danglers): every bare (same-store) id in any sources/chain must resolve
+  # to a node. Cross-store `<store>:<id>` refs resolve elsewhere and are not flagged.
+  def graph_i4(nodes)
+    findings = []
+    nodes.each do |id, edges|
+      %i[sources chain].each do |field|
+        edges[field].each do |ref|
+          next if cross_store_ref?(ref)
+          next if nodes.key?(ref)
+
+          findings << "#{id}.#{field} references #{ref} which resolves to no intent"
+        end
+      end
+    end
+    findings
+  end
+end

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

@@ -0,0 +1,209 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+
+# 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
+
+  # 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
+    { 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/lib/store_provisioning.rb

@@ -0,0 +1,100 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+# StoreProvisioning — the single source of truth for creating a registered
+# project's intent store (intent 61).
+#
+# A project can be registered in `projects.yml` yet have no store on disk. This
+# module deterministically and idempotently provisions that store at
+# `~/.plastic/projects/{slug}/store`: it makes the store directory, then writes,
+# only if missing, `.gitkeep`, `INDEX.md` (from templates/index.md), and
+# `project.yml` (from templates/project.yml). Re-running never clobbers existing
+# files. The logic was migrated here from the orphaned
+# `InstallerCore#bootstrap_project_store` so there is one definition that the
+# `provision-project-store` CLI, the `plastic-add-project-store` skill, the
+# doctor fix hint, and the project skills all consult.
+#
+# Pure filesystem and dependency-injected: `provision` accepts an injectable
+# `plastic_home` and `package_root` (so templates resolve from a known root and
+# tests stay hermetic), uses no `eval`, performs no qmd mutation, no `system`
+# or `spawn`, no network, and no global-constant injection. An unknown or
+# unregistered slug creates nothing and returns an error result.
+module StoreProvisioning
+  module_function
+
+  # Repo root resolved from this file's location (scripts/lib/), so templates
+  # resolve at package_root/templates/...; tests can inject a fake package_root.
+  PACKAGE_ROOT = File.expand_path("../..", __dir__)
+
+  # Provision the store for a registered project.
+  #
+  # Returns a result hash mirroring IntentValidator.validate's hash style:
+  #   { ok: true, store_dir: "...", created: [paths written this run] }
+  #   { ok: false, error: "..." }                (nothing is created)
+  def provision(slug, plastic_home: File.join(Dir.home, ".plastic"),
+                package_root: PACKAGE_ROOT)
+    unless registered?(slug, plastic_home)
+      return {
+        ok: false,
+        error: "project '#{slug}' is not registered in projects.yml; " \
+               "provisioning requires the project to already be registered",
+      }
+    end
+
+    project_dir = File.join(plastic_home, "projects", slug)
+    store_dir = File.join(project_dir, "store")
+    FileUtils.mkdir_p(store_dir)
+
+    created = []
+    created << write_if_missing(File.join(store_dir, ".gitkeep"), "")
+
+    index_template = File.join(package_root, "templates", "index.md")
+    if File.exist?(index_template)
+      created << write_if_missing(File.join(project_dir, "INDEX.md"),
+                                  File.read(index_template))
+    end
+
+    project_template = File.join(package_root, "templates", "project.yml")
+    if File.exist?(project_template)
+      created << write_if_missing(File.join(project_dir, "project.yml"),
+                                  File.read(project_template))
+    end
+
+    { ok: true, store_dir: store_dir, created: created.compact }
+  end
+
+  # True iff `slug` is a key under the `projects` mapping in projects.yml.
+  # Reads with a rescue-to-safe-default reader so a malformed file never raises.
+  def registered?(slug, plastic_home)
+    projects = load_projects(plastic_home)
+    projects.is_a?(Hash) && projects.key?(slug)
+  end
+
+  # Parse projects.yml -> the `projects` Hash, or {} on any error/absence.
+  # Mirrors QmdSync#load_projects (scripts/lib/qmd_sync.rb).
+  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
+
+  # Write `content` to `path` only when `path` does not exist. Returns the path
+  # when a file was written, or nil when the file already existed (so callers
+  # can build a `created` list). Copied from InstallerCore#write_if_missing.
+  def write_if_missing(path, content)
+    return nil if File.exist?(path)
+
+    File.write(path, content)
+    path
+  end
+end

package/scripts/migrate-to-global

@@ -17,7 +17,7 @@ GLOBAL_ROOT="$HOME/.plastic"
 LOCAL_PLASTIC="$PROJECT_PATH/.plastic"
 
 if [ ! -d "$GLOBAL_ROOT" ]; then
-  echo "Error: Global Plastic not installed. Run /plastic:install first." >&2
+  echo "Error: Global Plastic not installed. Run /plastic-install first." >&2
   exit 1
 fi