@zalom/plastic 1.2.0 → 1.4.0

package/scripts/lib/intent_validator.rb

@@ -37,9 +37,18 @@ module IntentValidator
   # (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)
+  # True iff `value` is a String matching the Folgezettel id form. When `known_stores` is
+  # given (an Array of store slugs, e.g. from StoreDiscovery.known_slugs), a cross-store
+  # prefix must also name a store in that set; a bare id (no prefix) is unaffected. When
+  # `known_stores` is nil (the default), only the shape is checked, so every existing
+  # caller keeps working unchanged (intent 189 D3).
+  def valid_id?(value, known_stores: nil)
+    s = value.to_s
+    return false unless s.match?(ID_PATTERN)
+    return true if known_stores.nil?
+
+    prefix = s[/\A([a-z0-9-]+):/, 1]
+    prefix.nil? || known_stores.include?(prefix)
   end
 
   # Read a file's YAML frontmatter, returning the parsed Hash (or {} when the
@@ -93,8 +102,10 @@ module IntentValidator
   end
 
   # PURE: given a parsed frontmatter Hash (or nil), return
-  # { ok: Boolean, missing: [field names], errors: [human strings] }.
-  def validate_frontmatter(fm)
+  # { ok: Boolean, missing: [field names], errors: [human strings] }. `known_stores`
+  # (optional, an Array of store slugs) is forwarded to valid_id? for each array-field
+  # element; when nil, only id shape is checked (unchanged existing behavior).
+  def validate_frontmatter(fm, known_stores: nil)
     unless fm.is_a?(Hash)
       return { ok: false, missing: REQUIRED_FIELDS.dup, errors: ["no frontmatter found"] }
     end
@@ -112,20 +123,37 @@ module IntentValidator
       end
 
       value.each do |element|
-        errors << "#{key} has invalid id: #{element.inspect}" unless valid_id?(element)
+        next if valid_id?(element, known_stores: known_stores)
+
+        errors << id_error(key, element, known_stores)
       end
     end
 
     { ok: missing.empty? && errors.empty?, missing: missing, errors: errors }
   end
 
+  # Build the rejection message for one bad id. Distinguishes a shape failure (never a
+  # valid Folgezettel form at all) from a known-store rejection (right shape, but the
+  # store prefix names a store that does not exist), so an agent can tell "typo'd id" apart
+  # from "made up a store" (intent 189 D3).
+  def id_error(key, element, known_stores)
+    s = element.to_s
+    prefix = known_stores && s.match?(ID_PATTERN) ? s[/\A([a-z0-9-]+):/, 1] : nil
+    if prefix
+      "#{key} has invalid id: #{element.inspect} (store #{prefix.inspect} is not a known " \
+        "store; known stores: #{known_stores.sort.join(", ")})"
+    else
+      "#{key} has invalid id: #{element.inspect}"
+    end
+  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))
+  def validate_content(content, known_stores: nil)
+    fm_result = validate_frontmatter(parse_frontmatter_text(content), known_stores: known_stores)
     sections = validate_sections(body_of(content))
     merge_sections(fm_result, sections)
   end
@@ -148,10 +176,10 @@ module IntentValidator
   # 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"))
+  def validate(intent_dir, plastic_home: File.join(Dir.home, ".plastic"), known_stores: nil)
     md_path = File.join(intent_dir, "#{File.basename(intent_dir)}.md")
     content = File.exist?(md_path) ? File.read(md_path) : nil
-    validate_content(content)
+    validate_content(content, known_stores: known_stores)
   end
 
   # PURE: cross-intent graph-shape invariants (intent 68). These need visibility

package/scripts/lib/links_gate.rb

@@ -0,0 +1,140 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "intent_validator"
+require_relative "links_section"
+require_relative "links_projection"
+require_relative "store_discovery"
+require_relative "graph_rebuild"
+
+# LinksGate, the write-time belt for the PLASTIC.md `## Links` contract
+# (intent 192). Pure decision logic plus a small store-scanning glue (mirrors
+# the glue ProjectLinks and Doctor each already carry independently for
+# themselves; the CALCULATION is shared via LinksSection/LinksProjection so
+# gate, projector, and doctor can never disagree by construction, even though
+# each IO shell still does its own discovery, exactly as project-links and
+# doctor already do today).
+#
+# #decision is the single entry point the PreToolUse hook
+# (scripts/hook-links-gate) calls: given a file path and its BEFORE/AFTER
+# content (BEFORE = on-disk, AFTER = the proposed Write/Edit result), it
+# returns nil (allow) or a deny message (String). It only ever judges the
+# REAL, fence-aware `## Links` section (LinksSection.extract_section); an
+# edit that leaves that section untouched is always allowed, cheaply, with no
+# store scan at all.
+module LinksGate
+  module_function
+
+  DENY_MESSAGE =
+    "PLASTIC LINKS GATE - a ## Links line must come from the frontmatter " \
+    "sources/chain graph, never be hand-typed. This edit changes the ## Links " \
+    "section to something other than its frontmatter projection. Add the edge " \
+    "to sources or chain in frontmatter instead, then run scripts/project-links " \
+    "to regenerate ## Links.".freeze
+
+  # True iff `path` is an intent file inside its own equally-named store
+  # directory (store/<id>--<slug>/<id>--<slug>.md). Mirrors the create-gate
+  # path matcher (intent 60b) so the two gates agree on what "an intent file" is.
+  def intent_file?(path)
+    return false if path.to_s.strip.empty?
+
+    abs = File.expand_path(path)
+    dir = File.dirname(abs)
+    dir.match?(%r{/store/[^/]+--[^/]+\z}) && File.basename(abs) == "#{File.basename(dir)}.md"
+  end
+
+  # Decide whether to deny a Write/Edit whose proposed result is
+  # `after_content` (the on-disk content before the edit is `before_content`,
+  # "" when the file does not yet exist). Returns nil (allow, including every
+  # "cannot judge" case) or DENY_MESSAGE.
+  def decision(file_path:, before_content:, after_content:, plastic_home:)
+    return nil unless intent_file?(file_path)
+
+    before_links = safe_extract(before_content)
+    after_links = safe_extract(after_content)
+    return nil if before_links.nil? || after_links.nil? # ambiguous ## Links; cannot judge
+    return nil if before_links == after_links # this edit does not touch ## Links at all
+
+    fm = IntentValidator.parse_frontmatter_text(after_content.to_s)
+    return nil unless fm.is_a?(Hash) # no parseable frontmatter; cannot judge
+
+    referer_store = store_key_for(file_path, plastic_home)
+    return nil unless referer_store # not under any discovered store; cannot judge
+
+    ctx = build_context(plastic_home)
+    resolve = ->(ref) do
+      LinksProjection.resolve_ref_projection(
+        ref, referer_store: referer_store, relocation_map: ctx[:relocation_map],
+             store_index: ctx[:store_index], node_index: ctx[:node_index]
+      )
+    end
+
+    expected =
+      begin
+        LinksProjection.section(sources: Array(fm["sources"]), chain: Array(fm["chain"]),
+                                 resolve: resolve)
+      rescue LinksProjection::UnresolvedRef
+        return nil # a pre-existing dead frontmatter ref is a doctor finding, not this gate's job
+      end
+
+    after_links == expected ? nil : DENY_MESSAGE
+  end
+
+  # Fence-aware real-section extract, tolerant of an ambiguous file (returns
+  # nil rather than raising, so #decision can fail open on it).
+  def safe_extract(content)
+    LinksSection.extract_section(IntentValidator.body_of(content.to_s))
+  rescue LinksSection::AmbiguousLinks
+    nil
+  end
+
+  # Which discovered store (by store_index/node_index key) `file_path` lives
+  # under, or nil when it is not inside any store this plastic_home discovers.
+  def store_key_for(file_path, plastic_home)
+    abs = File.expand_path(file_path)
+    store_dir = File.dirname(File.dirname(abs)) # .../<store>/<id>--<slug>/<file>.md
+    StoreDiscovery.discover(plastic_home)[:stores]
+      .find { |s| File.expand_path(s[:store]) == store_dir }
+      &.fetch(:key)
+  end
+
+  # Build the store_index/node_index/relocation_map resolver context spanning
+  # every discovered store, the same shape ProjectLinks#run and Doctor each
+  # build for themselves. Re-scanned per call (no caching): this only runs on
+  # the rare edit that actually changes ## Links, so the cost is paid where it
+  # matters, not on every Edit/Write.
+  def build_context(plastic_home)
+    discovery = StoreDiscovery.discover(plastic_home)
+    store_index = {}
+    node_index = {}
+    index_texts = {}
+
+    discovery[:stores].each do |s|
+      nodes = load_nodes(s[:store])
+      store_index[s[:key]] = nodes.keys
+      node_index[s[:key]] = nodes.transform_values { |v| { basename: v[:basename], label: v[:label] } }
+      index_texts[s[:key]] = File.exist?(s[:index]) ? File.read(s[:index]) : ""
+    end
+
+    { store_index: store_index, node_index: node_index,
+      relocation_map: GraphRebuild.build_relocation_map(index_texts) }
+  end
+
+  # { id => { basename:, label: } } for one store directory.
+  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] = { basename: entry, label: fm["intent"].to_s.strip }
+    end
+    nodes
+  end
+end

package/scripts/lib/links_projection.rb

@@ -27,14 +27,37 @@ module LinksProjection
   HEADING = "## Links"
   EMPTY_COMMENT = "<!-- No sources or chain; this intent has no graph edges to project. -->"
 
+  # A single rendered entry line, e.g. `- [[10--demo|Some intent]]` or
+  # `- [[knowdb:1--demo|Some intent]]`. The inverse of the line #entry renders.
+  ENTRY_LINE_RE = /\A- \[\[([^|\]]+)\|(.*)\]\]\z/
+
   # Raised when a sources/chain ref resolves to no intent. Carries the offending
-  # ref so the IO shell can report it per-intent and skip the write.
+  # ref, plus, when the resolver supplies one, the GraphRebuild status behind the
+  # miss (`:dead` or `:unknown_store`), so a rescuer can tell "genuinely gone" apart
+  # from "store not discovered this run, left untouched" instead of one generic
+  # failure. `reason` is nil when the resolver has no status to report (a live
+  # store/id whose node_index lookup still misses).
   class UnresolvedRef < StandardError
-    attr_reader :ref
+    attr_reader :ref, :reason
 
-    def initialize(ref)
+    def initialize(ref, reason: nil, store: nil)
       @ref = ref
-      super("unresolved sources/chain ref: #{ref.inspect}")
+      @reason = reason
+      super("#{message_for(reason, store)}: #{ref.inspect}")
+    end
+
+    private
+
+    def message_for(reason, store)
+      case reason
+      when :dead
+        "unresolved sources/chain ref (dead, resolves to no intent)"
+      when :unknown_store
+        "unresolved sources/chain ref (unknown store #{store.inspect}, not discovered " \
+          "this run; left untouched, verify store discovery)"
+      else
+        "unresolved sources/chain ref"
+      end
     end
   end
 
@@ -76,6 +99,33 @@ module LinksProjection
     "#{HEADING}\n#{EMPTY_COMMENT}\n"
   end
 
+  # PURE. Parse a rendered or extracted `## Links` section's entry lines back into
+  # [{target:, label:}], in the order they appear. Ignores the heading line and the
+  # empty-state comment (and any other line that is not a `- [[target|label]]`
+  # line). The structural inverse of #entry's line shape. Used by callers
+  # (project-links) that need to compare or merge an OLD section's entries
+  # against a freshly-computed canonical one, one level below #section's own
+  # resolve-and-render.
+  def parse_entries(text)
+    text.to_s.each_line.filter_map do |line|
+      m = line.chomp.match(ENTRY_LINE_RE)
+      m && { target: m[1], label: m[2] }
+    end
+  end
+
+  # PURE. Render a final `## Links` block from an ALREADY-RESOLVED, ALREADY
+  # ORDERED list of {target:, label:} entries (no resolve callable; the caller
+  # has already done resolution/merging, e.g. project-links merging canonical
+  # entries with preserved orphan entries). Falls back to the empty-state
+  # comment when `entries` is empty. Shares the heading/line format with
+  # #section so the two can never render a different shape for the same list.
+  def render_entries(entries)
+    list = Array(entries)
+    return empty_section if list.empty?
+
+    (["#{HEADING}\n"] + list.map { |e| "- [[#{e[:target]}|#{e[:label]}]]\n" }).join
+  end
+
   # Resolve `ref`, render its entry, and append it to `rendered` UNLESS its resolved
   # target was already emitted (dedup by resolved target, first-seen wins so sources
   # precede chain). Mutates `seen` and `rendered`. Raises UnresolvedRef on a miss.
@@ -88,13 +138,18 @@ module LinksProjection
   end
 
   # PURE. Resolve one ref to [target, label]. Raises UnresolvedRef when the
-  # resolver returns nothing usable.
+  # resolver returns nothing usable, carrying whatever :reason/:store the
+  # resolver supplied (see #resolve_ref_projection) so the miss stays
+  # distinguishable at the IO shell.
   def resolve_entry(ref, resolve)
     resolved = resolve.call(ref)
-    target = resolved.is_a?(Hash) ? resolved[:target] || resolved["target"] : nil
-    raise UnresolvedRef, ref if target.nil? || target.to_s.strip.empty?
+    hash = resolved.is_a?(Hash) ? resolved : {}
+    target = hash[:target] || hash["target"]
+    if target.nil? || target.to_s.strip.empty?
+      raise UnresolvedRef.new(ref, reason: hash[:reason], store: hash[:store])
+    end
 
-    label = (resolved[:label] || resolved["label"]).to_s.strip
+    label = (hash[:label] || hash["label"]).to_s.strip
     [target.to_s, label]
   end
 
@@ -117,8 +172,10 @@ module LinksProjection
   #   node_index     — { store_key => { id => { basename:, label: } } } (spans all stores)
   #
   # Returns { target:, label: } (target is `<id>--<slug>` for a same-store id, or
-  # `<slug>:<id>--<slug>` for a cross-store one), or nil when the ref resolves to no
-  # live intent (which makes #section / #entry raise UnresolvedRef).
+  # `<slug>:<id>--<slug>` for a cross-store one). On a miss, returns { reason: :dead }
+  # or { reason: :unknown_store, store: } instead of a bare nil, so #resolve_entry can
+  # raise UnresolvedRef with a distinguishable message (#section / #entry still raise
+  # either way; only the message differs).
   #
   # Uses GraphRebuild.resolve_ref so a relocation always wins over a coincidentally
   # reused id (the `global:24` impostor hazard), exactly as the frontmatter rebuild
@@ -142,8 +199,10 @@ module LinksProjection
       return nil if node.nil?
 
       { target: "#{slug}:#{node[:basename]}", label: node[:label] }
-    else # :dead
-      nil
+    when :dead
+      { reason: :dead }
+    when :unknown_store
+      { reason: :unknown_store, store: res[:store] }
     end
   end
 

package/scripts/lib/power_tools.rb

@@ -3,17 +3,18 @@
 
 require_relative "qmd_sync"
 
-# PowerTools — detect-then-degrade harness for Plastic's optional power-tools
-# (intent 66b; demoted to recommendations in intent 108, D8). It owns
-# deterministic detection of each tool and builds a RECOMMENDATION string for
-# whichever tools are present, so the agent is reminded (not obliged) to prefer
-# them: QMD for finding intents, Serena for code navigation.
+# PowerTools - detect-then-degrade harness for Plastic's optional power-tools
+# (intent 66b; demoted to recommendations in intent 108, D8; Enola added in
+# intent 187). It owns deterministic detection of each tool and builds a
+# RECOMMENDATION string for whichever tools are present, so the agent is
+# reminded (not obliged) to prefer them: QMD for finding intents, Enola or
+# Serena for code navigation.
 #
 # Strictly detect-then-degrade: a tool that is absent contributes nothing, and
 # `mandate` returns nil when no tool is present. Nothing here installs anything.
 #
 # Pure and dependency-injected: every detection runs through an injected callable
-# or keyword probe (PATH scan / `.serena` marker walk), so the whole module is
+# or keyword probe (PATH scan / marker-directory walk), so the whole module is
 # unit-testable with no real binaries, no network, and no global/ENV state.
 module PowerTools
   module_function
@@ -31,6 +32,15 @@ module PowerTools
     !!path_probe.call
   end
 
+  # True when Enola is present: a `.enola` directory exists in cwd or any
+  # ancestor (a generated snapshot), OR `enola` is resolvable on PATH. Both
+  # probes are injectable so tests do not depend on the host having Enola
+  # installed or indexed (intent 187).
+  def enola?(cwd:, path_probe: method(:which_enola), marker_finder: method(:enola_marker?))
+    return true if marker_finder.call(cwd)
+    !!path_probe.call
+  end
+
   # True when `serena` is an executable on PATH. Mirrors QmdSync.which_qmd.
   def which_serena
     ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
@@ -39,6 +49,14 @@ module PowerTools
     end
   end
 
+  # True when `enola` is an executable on PATH. Mirrors which_serena.
+  def which_enola
+    ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
+      candidate = File.join(dir, "enola")
+      File.file?(candidate) && File.executable?(candidate)
+    end
+  end
+
   # Walk up from cwd to the filesystem root, returning true if any level holds a
   # `.serena` directory.
   def serena_marker?(cwd)
@@ -52,26 +70,51 @@ module PowerTools
     false
   end
 
+  # Walk up from cwd to the filesystem root, returning true if any level holds
+  # an `.enola` directory (a generated snapshot).
+  def enola_marker?(cwd)
+    dir = File.expand_path(cwd)
+    loop do
+      return true if Dir.exist?(File.join(dir, ".enola"))
+      parent = File.dirname(dir)
+      break if parent == dir
+      dir = parent
+    end
+    false
+  end
+
   QMD_OBLIGATION = "prefer `qmd search` / `qmd query` over the `plastic-*` " \
                    "collections to check for existing or related intents before " \
                    "treating work as new"
   SERENA_OBLIGATION = "prefer its symbolic tools (find_symbol / get_symbols_overview / " \
                        "find_referencing_symbols) for code navigation"
+  ENOLA_OBLIGATION = "prefer its MCP symbol resolution (or `.enola/facts.jsonl`) for " \
+                     "code navigation over grep"
 
   # Recommendation text for whichever tools are present, or nil when none are.
-  # Both present collapse to ONE combined line naming both obligations (no
-  # embedded newline); one present returns that tool's own line; neither
-  # returns nil.
-  def mandate(cwd:, qmd_detector: QmdSync.method(:detect), serena_detector: nil)
+  # QMD plus a code-navigation tool collapse to ONE combined line naming both
+  # obligations (no embedded newline); one tool present returns that tool's own
+  # line; neither returns nil.
+  #
+  # Enola-first: Enola and Serena share ONE code-navigation slot. When both are
+  # present, only Enola is named (intent 187, matching the owner's standing
+  # Enola-first ruling and avoiding a bloated three-tool line). The QMD-only and
+  # Serena-only lines are unchanged from before Enola existed.
+  def mandate(cwd:, qmd_detector: QmdSync.method(:detect), serena_detector: nil, enola_detector: nil)
     qmd_present = qmd?(detector: qmd_detector)
+    enola_present = enola_detector ? !!enola_detector.call : enola?(cwd: cwd)
     serena_present = serena_detector ? !!serena_detector.call : serena?(cwd: cwd)
 
-    if qmd_present && serena_present
-      "QMD and Serena are available: #{QMD_OBLIGATION}, and #{SERENA_OBLIGATION}."
+    nav_present = enola_present || serena_present
+    nav_name = enola_present ? "Enola" : "Serena"
+    nav_obligation = enola_present ? ENOLA_OBLIGATION : SERENA_OBLIGATION
+
+    if qmd_present && nav_present
+      "QMD and #{nav_name} are available: #{QMD_OBLIGATION}, and #{nav_obligation}."
     elsif qmd_present
       "QMD is available: #{QMD_OBLIGATION}."
-    elsif serena_present
-      "Serena is available: #{SERENA_OBLIGATION}."
+    elsif nav_present
+      "#{nav_name} is available: #{nav_obligation}."
     end
   end
 end

package/scripts/lib/project_validator.rb

@@ -0,0 +1,113 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+
+# ProjectValidator - the single source of truth for "is a project spawn
+# complete?" (intent 190).
+#
+# A project can be registered in projects.yml, have a store, and still be
+# missing the pieces a real project needs: project.yml, a root AGENTS.md.
+# The intent-26 spawn shipped exactly that shape and was caught only by a
+# much later, pull-only plastic-doctor sweep. This module lets
+# plastic-project-creating verify a spawn BEFORE announcing it as done,
+# mirroring how scripts/new-intent already runs IntentValidator before
+# announcing a new intent (validate-intent).
+#
+# Pure and dependency-injected: validate accepts an injectable plastic_home,
+# uses no eval, performs no file writes, no global-constant injection.
+# scripts/doctor.rb's check_project_store already covers 4 of these 6
+# invariants (project_dir_exists, project_store_dir, project_index,
+# project_yml_exists) plus cross_references, advisorially and pull-only;
+# doctor adopting this module is a named follow-up, not part of this intent
+# (D8). Invariant 4 (project-root AGENTS.md) has no existing check anywhere.
+module ProjectValidator
+  module_function
+
+  def validate(slug, plastic_home: File.join(Dir.home, ".plastic"))
+    missing = []
+    errors = []
+
+    entry = registration_for(slug, plastic_home)
+    unless entry
+      missing << "projects.yml registration"
+      errors << "project '#{slug}' is not registered in projects.yml with a 'path' key"
+      return { ok: false, missing: missing, errors: errors }
+    end
+
+    project_path = entry["path"].to_s
+
+    # Invariant 2: registered project directory exists on disk.
+    unless File.directory?(project_path)
+      missing << "project directory"
+      errors << "registered project directory does not exist: #{project_path}"
+    end
+
+    project_dir = File.join(plastic_home, "projects", slug)
+
+    # Invariant 3: project.yml exists AND parses as YAML.
+    project_yml_path = File.join(project_dir, "project.yml")
+    if File.exist?(project_yml_path)
+      parsed = begin
+        YAML.safe_load(File.read(project_yml_path))
+      rescue StandardError
+        nil
+      end
+      unless parsed.is_a?(Hash)
+        missing << "project.yml (valid YAML)"
+        errors << "project.yml exists at #{project_yml_path} but does not parse as YAML"
+      end
+    else
+      missing << "project.yml"
+      errors << "project.yml missing at #{project_yml_path}"
+    end
+
+    # Invariant 4: project-root AGENTS.md (the registered path, NOT
+    # ~/.plastic/projects/{slug}/). This is the intent-26 spawn's gap,
+    # uncaught by doctor.rb today.
+    agents_md_path = File.join(project_path, "AGENTS.md")
+    unless File.exist?(agents_md_path)
+      missing << "AGENTS.md (project root)"
+      errors << "AGENTS.md missing at project root: #{agents_md_path}"
+    end
+
+    # Invariant 5: store/ exists.
+    store_dir = File.join(project_dir, "store")
+    unless File.directory?(store_dir)
+      missing << "store/"
+      errors << "store directory missing: #{store_dir}"
+    end
+
+    # Invariant 6: INDEX.md exists.
+    index_md_path = File.join(project_dir, "INDEX.md")
+    unless File.exist?(index_md_path)
+      missing << "INDEX.md"
+      errors << "INDEX.md missing: #{index_md_path}"
+    end
+
+    { ok: missing.empty?, missing: missing, errors: errors }
+  end
+
+  # Invariant 1: registered in projects.yml with a 'path'. Returns the
+  # project's entry Hash, or nil when unregistered or the entry has no path.
+  def registration_for(slug, plastic_home)
+    projects = load_projects(plastic_home)
+    entry = projects[slug]
+    entry.is_a?(Hash) && entry["path"] ? entry : nil
+  end
+
+  # Parse projects.yml -> the `projects` Hash, or {} on any error/absence.
+  # Mirrors StoreProvisioning.load_projects.
+  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
+end

package/scripts/lib/qmd_hook.rb

@@ -4,14 +4,15 @@
 require_relative "qmd_sync"
 require_relative "power_tools"
 
-# QmdHook — decision logic for the power-tools UserPromptSubmit hook (intents 66,
+# QmdHook - decision logic for the power-tools UserPromptSubmit hook (intents 66,
 # 66b). 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).
 #
 # When qmd is present it still injects scored qmd hits (intent 66), then appends
-# the PowerTools mandate (a MUST obligation per present tool: qmd for finding
-# intents, serena for code navigation) instead of the old soft reminder.
+# the PowerTools mandate (a recommendation per present tool: qmd for finding
+# intents, Enola-first for code navigation, falling back to Serena; intent 187
+# added the enola_detector alongside the pre-existing serena_detector).
 module QmdHook
   module_function
 
@@ -19,11 +20,13 @@ module QmdHook
 
   def run(prompt:, cwd:, plastic_home:, runner: QmdSync.default_runner,
           detector: QmdSync.method(:detect), limit: 3, min_score: 0.5,
-          serena_detector: nil)
+          serena_detector: nil, enola_detector: nil)
     serena_detector ||= -> { PowerTools.serena?(cwd: cwd) }
+    enola_detector ||= -> { PowerTools.enola?(cwd: cwd) }
     qmd_present = !!detector.call
     serena_present = !!serena_detector.call
-    return nil unless qmd_present || serena_present
+    enola_present = !!enola_detector.call
+    return nil unless qmd_present || serena_present || enola_present
 
     p = prompt.to_s.strip
     # The hit SEARCH is the only expensive step and the only one gated by prompt
@@ -37,19 +40,20 @@ module QmdHook
       hits = QmdSync.search(p, collections: collections, limit: limit,
                             min_score: min_score, runner: runner, detector: detector)
       if hits.any?
-        parts << "Related / prior Plastic intents (qmd BM25, includes completed) — " \
+        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]}"
+          parts << "- [#{pct}%] #{loc} - #{h[:title]}"
         end
         parts << ""
       end
     end
 
     mandate = PowerTools.mandate(cwd: cwd, qmd_detector: -> { qmd_present },
-                                 serena_detector: -> { serena_present })
+                                 serena_detector: -> { serena_present },
+                                 enola_detector: -> { enola_present })
     parts << mandate if mandate
     return nil if parts.empty?
     parts.join("\n")