@zalom/plastic 1.3.0 → 1.4.0

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")

package/scripts/lib/restore_intent_v1.rb

@@ -0,0 +1,154 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "graph_rebuild"
+require_relative "frontmatter_writer"
+
+# RestoreIntentV1 - pure graph math for restoring a completed intent's frontmatter
+# graph across a v1 prose revert (intent 193). No file IO, no git, no `system`.
+#
+# The rule this module carries: prose reverts to v1; the sources/chain graph is
+# APPEND-ONLY and is the UNION of the v1 snapshot and the current snapshot, never
+# a re-derivation from other intents' reciprocal edges (that would silently erase
+# legitimate I2-asymmetry edges doctor.rb never auto-fixes). Before the union is
+# written, every edge (from either snapshot) is target-resolved by reusing
+# GraphRebuild.resolve_ref verbatim, the same classifier rebuild-graph and
+# doctor.rb already share: a :dead edge (resolves to no id in any known store) is
+# dropped and reported; :same_store, :cross_store, and :unknown_store edges are
+# all kept (bias toward preserving an edge that might be real; only positive proof
+# of non-existence justifies a drop). The value WRITTEN for a kept edge is the
+# RESOLVED value GraphRebuild returns (classification[:id] for :same_store,
+# classification[:ref] for :cross_store), never the raw pre-resolution ref, so
+# this tool can never disagree with rebuild-graph/doctor about the canonical form
+# of an edge it just wrote (D14).
+module RestoreIntentV1
+  module_function
+
+  # PURE. Computes the desired sources/chain for a restore.
+  #
+  # Returns:
+  #   { sources: [...], chain: [...],
+  #     dropped:      [ { field: :sources|:chain, ref: "<id or store:id>" }, ... ],
+  #     unverified:   [ { field: :sources|:chain, ref: "<id or store:id>" }, ... ],
+  #     current_only: [ { field: :sources|:chain, ref: "<id or store:id>" }, ... ] }
+  #
+  # `current_only` names every edge present in the CURRENT snapshot but absent from
+  # the v1 snapshot (D3 transparency): an edge added by the very change being
+  # reverted, which the union now carries forward. Named explicitly regardless of
+  # its target-resolution outcome, so it is never a silent side effect.
+  def compute_graph(v1_sources:, v1_chain:, current_sources:, current_chain:,
+                     referer_store:, relocation_map:, store_index:)
+    sources_result = resolve_union(v1_sources, current_sources, :sources,
+                                    referer_store, relocation_map, store_index)
+    chain_result = resolve_union(v1_chain, current_chain, :chain,
+                                  referer_store, relocation_map, store_index)
+
+    {
+      sources: sources_result[:kept],
+      chain: chain_result[:kept],
+      dropped: sources_result[:dropped] + chain_result[:dropped],
+      unverified: sources_result[:unverified] + chain_result[:unverified],
+      current_only: current_only_edges(v1_sources, current_sources, :sources) +
+                    current_only_edges(v1_chain, current_chain, :chain),
+    }
+  end
+
+  # PURE. Union two edge arrays (deduped, order-preserving, first array's order
+  # wins for shared entries), then target-resolve each via GraphRebuild.resolve_ref.
+  # WRITES THE RESOLVED VALUE, not the raw union member: a redundant same-store
+  # prefix (e.g. "global:15" written by a "global" intent) collapses to the bare
+  # "15", and a relocated ref is repointed to its resolved "store:id" form, exactly
+  # matching what GraphRebuild.rebuild_store itself writes (res[:id] / res[:ref]).
+  # Resolution can make two distinct union members collapse to the same resolved
+  # value, so `kept` is de-duped again after resolution.
+  def resolve_union(v1_edges, current_edges, field, referer_store, relocation_map, store_index)
+    union = (Array(v1_edges).map(&:to_s) + Array(current_edges).map(&:to_s)).uniq
+    kept = []
+    dropped = []
+    unverified = []
+
+    union.each do |ref|
+      classification = GraphRebuild.resolve_ref(
+        ref, referer_store: referer_store, relocation_map: relocation_map, store_index: store_index
+      )
+      case classification[:status]
+      when :dead
+        dropped << { field: field, ref: ref }
+      when :unknown_store
+        kept << ref
+        unverified << { field: field, ref: ref }
+      when :same_store
+        kept << classification[:id]
+      when :cross_store
+        kept << classification[:ref]
+      end
+    end
+
+    { kept: kept.uniq, dropped: dropped, unverified: unverified }
+  end
+
+  # PURE. Every edge present in `current_edges` but absent from `v1_edges`
+  # (raw, before target resolution): the set the restore is about to carry
+  # forward that v1 itself never had.
+  def current_only_edges(v1_edges, current_edges, field)
+    v1_set = Array(v1_edges).map(&:to_s)
+    Array(current_edges).map(&:to_s).uniq.reject { |ref| v1_set.include?(ref) }
+                         .map { |ref| { field: field, ref: ref } }
+  end
+
+  # PURE. Reapply the computed graph onto v1's exact prose. Delegates entirely to
+  # FrontmatterWriter; this module never rewrites YAML itself.
+  def apply_graph(v1_content, desired_sources:, desired_chain:)
+    FrontmatterWriter.rewrite_arrays(v1_content, sources: desired_sources, chain: desired_chain)
+  end
+
+  # PURE. Render one revisions.md entry (intent 107's append-only, move-and-record
+  # convention). `n` is the next revision number for this intent's revisions.md.
+  # `files` names every file reverted to its v1 content in this restore.
+  def render_revision_entry(n, at:, timestamp:, files:, before_sources:, after_sources:,
+                             before_chain:, after_chain:, dropped:)
+    lines = []
+    lines << "## Revision v#{n} - #{timestamp}"
+    lines << "- Why: restore-to-v1 preserved the frontmatter graph across a completed-intent " \
+             "restore [rule: restored-to-v1]"
+    lines << "- Prior location: frontmatter - sources/chain; prose reverted to ref #{at}"
+    lines << "- Files reverted to v1: #{files.empty? ? "(none, already at v1)" : files.join(", ")}"
+    lines << "- Change: sources (before: #{before_sources.inspect} -> after: #{after_sources.inspect}); " \
+             "chain (before: #{before_chain.inspect} -> after: #{after_chain.inspect})"
+    unless dropped.empty?
+      lines << ""
+      dropped.each do |d|
+        lines << "  Dropped dead edge in #{d[:field]} -> #{d[:ref]}: target intent does not exist."
+      end
+    end
+    "#{lines.join("\n")}\n"
+  end
+
+  # PURE. Render the dry-run/apply human-readable report. `v1` and `current` are
+  # { sources:, chain: } snapshots shown alongside the resulting union so a
+  # reviewer can see all three shapes without recomputing anything by hand (spec
+  # acceptance criterion: dry-run prints the v1 graph, the current graph, and the
+  # resulting union, not only the union).
+  def render_report(base:, at:, prose_changes:, v1:, current:, graph:, apply:)
+    lines = []
+    lines << "restore-intent-v1: #{base} at #{at} (#{apply ? "APPLY" : "DRY RUN"})"
+    prose_changes.each { |f| lines << "  prose: revert #{f}" }
+    lines << "  v1 sources -> #{v1[:sources].inspect}"
+    lines << "  v1 chain -> #{v1[:chain].inspect}"
+    lines << "  current sources -> #{current[:sources].inspect}"
+    lines << "  current chain -> #{current[:chain].inspect}"
+    lines << "  union sources -> #{graph[:sources].inspect}"
+    lines << "  union chain -> #{graph[:chain].inspect}"
+    graph[:dropped].each do |d|
+      lines << "  DROPPED dead edge (#{d[:field]}): #{d[:ref]} - target intent does not exist"
+    end
+    graph[:unverified].each do |d|
+      lines << "  UNVERIFIED edge (#{d[:field]}): #{d[:ref]} - store unknown, kept"
+    end
+    graph[:current_only].each do |d|
+      lines << "  CURRENT-ONLY edge (#{d[:field]}): #{d[:ref]} - added by the change being " \
+               "reverted, now surviving the restore"
+    end
+    lines.join("\n")
+  end
+end

package/scripts/lib/roadmap_queue.rb

@@ -112,7 +112,7 @@ class RoadmapQueue
 
   def parse_roadmap(path)
     text = File.read(path)
-    { slug: File.basename(path, ".md"), path: path, waves: parse_waves(section_body(text, "Waves")) }
+    { slug: File.basename(path, ".md"), path: path, waves: parse_waves(RoadmapSavepoint.grouping_section_body(text, path: path)) }
   end
 
   def parse_waves(waves_body)

package/scripts/lib/roadmap_savepoint.rb

@@ -21,12 +21,20 @@ require "fileutils"
 module RoadmapSavepoint
   module_function
 
-  EVENTS = %w[created dispatched parked merged release handoff closed added reordered wave].freeze
+  EVENTS = %w[created dispatched parked merged release handoff closed added reordered wave batch].freeze
+
+  # Raised by grouping_section_body when a roadmap has neither '## Batches' (canonical, owner
+  # ruling 145) nor '## Waves' (legacy) as its top-level grouping heading (intent 196): a
+  # malformed roadmap must fail loudly, never silently parse as zero entries.
+  class MissingGroupingHeading < StandardError; end
+
+  # Canonical first, legacy fallback second. A roadmap file has exactly one of these, never both.
+  GROUPING_HEADINGS = %w[Batches Waves].freeze
 
   # Keyword -> event classification for `rebuild`, checked top to bottom, first match wins.
   # Kept small and deterministic (action 1). Order matters: more specific/rarer words are
-  # checked before the broader "wave" fallback so an incidental "wave" mention in an otherwise
-  # classifiable line never shadows its real event.
+  # checked before the broader "wave"/"batch" fallbacks so an incidental "wave" or "batch"
+  # mention in an otherwise classifiable line never shadows its real event.
   KEYWORD_TABLE = [
     [/\bclosed\b/i, "closed"],
     [/\bhanded off\b|\bhandoff\b/i, "handoff"],
@@ -38,6 +46,7 @@ module RoadmapSavepoint
     [/\badded\b|\badds\b/i, "added"],
     [/\bcreated\b/i, "created"],
     [/\bwave\b/i, "wave"],
+    [/\bbatch(?:es)?\b/i, "batch"],
   ].freeze
 
   # --- append -----------------------------------------------------------------
@@ -88,15 +97,16 @@ module RoadmapSavepoint
   # --- rebuild ------------------------------------------------------------------
 
   # Reconstruct the paired ledger deterministically from the roadmap file's `## Log` (never the
-  # roadmap `.md`, which is read-only here), cross-checked against `## Waves` and the tier's
-  # INDEX so every `delivered` wave entry has a `merged` line. Every timestamp comes from an
-  # on-disk source (the Log, or INDEX `## Completed`); an entry with no recoverable timestamp is
-  # not emitted (D4, never invented). Overwrites the ledger (the one operation allowed to rewrite
-  # it, matching `Bridge.rebuild_savepoint`). Returns the number of lines written.
+  # roadmap `.md`, which is read-only here), cross-checked against the roadmap's grouping
+  # section (`## Batches`, or legacy `## Waves`) and the tier's INDEX so every `delivered` wave
+  # entry has a `merged` line. Every timestamp comes from an on-disk source (the Log, or INDEX
+  # `## Completed`); an entry with no recoverable timestamp is not emitted (D4, never invented).
+  # Overwrites the ledger (the one operation allowed to rewrite it, matching
+  # `Bridge.rebuild_savepoint`). Returns the number of lines written.
   def rebuild(roadmap_path)
     text = File.read(roadmap_path)
     log_lines = classify_log(section_body(text, "Log"))
-    delivered_ids = delivered_wave_ids(section_body(text, "Waves"))
+    delivered_ids = delivered_wave_ids(grouping_section_body(text, path: roadmap_path))
     backfilled = backfill_merged_lines(log_lines, delivered_ids, roadmap_path)
 
     lines = dedup_pairs(log_lines + backfilled)
@@ -139,7 +149,8 @@ module RoadmapSavepoint
 
   WAVE_ENTRY = /\A-\s*\[([ xX])\]\s+(\S+)\s+.+—\s*(\S+)\s*\z/.freeze
 
-  # Intent ids of every `[x] ... — delivered` entry in the `## Waves` body.
+  # Intent ids of every `[x] ... — delivered` entry in the roadmap's grouping section body
+  # (`## Batches`, or legacy `## Waves`).
   def delivered_wave_ids(waves_body)
     waves_body.each_line.filter_map do |line|
       m = line.strip.match(WAVE_ENTRY)
@@ -198,6 +209,23 @@ module RoadmapSavepoint
   end
   private_class_method :section_body
 
+  # The one shared fix point for the Batches/Waves grammar (intent 196). '## Batches' is
+  # canonical (owner ruling 145); '## Waves' is the legacy heading the three pre-ruling roadmaps
+  # still use and must keep parsing forever (145 also forbids renaming those files). Public,
+  # because roadmap_queue.rb calls it instead of holding its own copy of the heading string: that
+  # file already depends one-directionally on this module (require_relative "roadmap_savepoint",
+  # already calling `ledger_path_for`), so this is the smaller diff than a new shared module.
+  # Raises MissingGroupingHeading, naming the offending path, when neither heading is present.
+  def grouping_section_body(text, path: nil)
+    GROUPING_HEADINGS.each do |heading|
+      m = text.match(/^##\s+#{Regexp.escape(heading)}\s*$(.*?)(?=^##\s|\z)/m)
+      return m[1] if m
+    end
+    raise MissingGroupingHeading,
+          "#{path || '(unknown roadmap file)'}: found neither '## Batches' (canonical) nor " \
+          "'## Waves' (legacy) grouping heading"
+  end
+
   # Stable dedup on the `(event, detail)` pair, keeping the first occurrence in the given
   # (already chronological-then-backfill-appended) order.
   def dedup_pairs(lines)

package/scripts/lib/store_discovery.rb

@@ -0,0 +1,77 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "store_provisioning"
+
+# StoreDiscovery: the single source of truth for "what stores exist" (intent 189).
+#
+# Two failure modes must both be avoided: missing a real store (a live cross-store ref
+# into it gets classified dead and DELETED by rebuild-graph, the data-loss bug this module
+# fixes) and silently treating a registered-but-unprovisioned project as an empty store (a
+# different silent failure). So discovery is a SUPERSET: the global store (if it exists)
+# plus every `projects/<slug>/store` directory that exists on disk, UNIONED with every slug
+# registered in projects.yml. A registered slug with no store directory contributes no ids
+# and is reported separately in `missing`, never silently dropped.
+#
+# Reuses StoreProvisioning.load_projects (rescues to {} so a malformed projects.yml never
+# raises) instead of writing a third copy of that reader (a second copy already exists in
+# QmdSync, out of scope here).
+#
+# Pure filesystem, dependency-injected: `discover` takes `plastic_home` as its only
+# argument, performs no writes, no `system`/`spawn`, no network, no eval, no
+# ENV/global-constant reads.
+module StoreDiscovery
+  module_function
+
+  # Returns { stores: [ { key:, slug:, root:, store:, index: } ... ],
+  #           missing: [ { slug:, project_dir: } ... ] }.
+  #
+  # `stores` entries: `key` is "global" or "project:<slug>" (the store_index/referer_store
+  # key shape GraphRebuild and the doctor checks already use); `slug` is the bare token
+  # form used in a cross-store ref ("global", "knowdb", "ai-agents-resources"); `root` is
+  # the directory holding INDEX.md; `store` is the intents directory; `index` is the
+  # INDEX.md path. Sorted by slug (global first) for deterministic output.
+  #
+  # `missing` lists every projects.yml slug with no `store/` directory on disk: legal
+  # (plastic-store-provisioning exists for exactly this state), reported so callers never
+  # mistake it for a store with zero intents.
+  def discover(plastic_home)
+    stores = []
+    missing = []
+
+    global_store = File.join(plastic_home, "store")
+    if File.directory?(global_store)
+      stores << { key: "global", slug: "global", root: plastic_home,
+                  store: global_store, index: File.join(plastic_home, "INDEX.md") }
+    end
+
+    registered = StoreProvisioning.load_projects(plastic_home) # { slug => info }, {} on error/absence
+    projects_root = File.join(plastic_home, "projects")
+    on_disk = File.directory?(projects_root) ? Dir.children(projects_root).reject { |e| e.start_with?(".") } : []
+
+    all_slugs = (registered.keys + on_disk).uniq.sort
+
+    all_slugs.each do |slug|
+      root = File.join(projects_root, slug)
+      store_dir = File.join(root, "store")
+      if File.directory?(store_dir)
+        stores << { key: "project:#{slug}", slug: slug, root: root,
+                    store: store_dir, index: File.join(root, "INDEX.md") }
+      elsif registered.key?(slug)
+        missing << { slug: slug, project_dir: root }
+      end
+      # else: an on-disk directory with no store/ and no projects.yml entry (a junk dir,
+      # e.g. a stale path-as-slug from a past bug). Silently excluded, exactly as doctor's
+      # existing disk scan already does: it is neither a store nor a registered project.
+    end
+
+    { stores: stores, missing: missing }
+  end
+
+  # Convenience: just the known store SLUGS (the token form used in a cross-store ref),
+  # for IntentValidator's injected known-store check (ACTION_7). "global" is included
+  # when the global store exists.
+  def known_slugs(plastic_home)
+    discover(plastic_home)[:stores].map { |s| s[:slug] }
+  end
+end

package/scripts/lib/store_provisioning.rb

@@ -44,24 +44,33 @@ module StoreProvisioning
       }
     end
 
+    index_template = File.join(package_root, "templates", "index.md")
+    project_template = File.join(package_root, "templates", "project.yml")
+
+    missing = []
+    missing << "templates/index.md" unless File.exist?(index_template)
+    missing << "templates/project.yml" unless File.exist?(project_template)
+
+    unless missing.empty?
+      return {
+        ok: false,
+        error: "cannot provision project '#{slug}': missing required " \
+               "template(s) #{missing.join(", ")} under #{package_root}/templates. " \
+               "This means the installer did not ship these templates to " \
+               "package_root/templates: check InstallerCore#core_files registers " \
+               "every templates/* file, then re-run the Plastic installer (or " \
+               "'plastic update') so package_root has current templates.",
+      }
+    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
+    created << write_if_missing(File.join(project_dir, "INDEX.md"), File.read(index_template))
+    created << write_if_missing(File.join(project_dir, "project.yml"), File.read(project_template))
 
     { ok: true, store_dir: store_dir, created: created.compact }
   end