@zalom/plastic 1.3.0 → 1.4.0

package/scripts/lib/config_asks.rb

@@ -0,0 +1,110 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+
+# Shared resolution for config_asks.yml: a shipped, declarative manifest that
+# lets a release announce a brand new config question without editing
+# update.rb, doctor.rb, or any skill. Sibling of deprecations.yml (announce
+# only); this one also tracks whether the user has answered or dismissed each
+# entry, via config_asks_dismissed (mirrors deprecations_dismissed).
+#
+# Footgun for whoever adds the next entry: pending reads config.yml directly
+# and never merges in read-config's DEFAULTS, so keying a new entry on
+# something that already has a non-nil value in read-config's DEFAULTS would
+# make that entry look unset, and therefore pending, forever, even though the
+# rest of Plastic already treats it as answered by that default. See the
+# matching note in config_asks.yml's schema header.
+module ConfigAsks
+  FILENAME = "config_asks.yml"
+
+  # nil if the manifest is absent (a legitimate no-op: no release has declared
+  # a config question yet) or valid. A short description of the problem if the
+  # file exists but could not be read or parsed, or does not declare a
+  # config_asks array. Callers use this to tell "nothing declared" apart from
+  # "declared but broken" -- the manifest being unreadable must never look
+  # like a clean pass.
+  def self.manifest_error(plastic_home)
+    path = File.join(plastic_home, FILENAME)
+    return nil unless File.exist?(path)
+
+    data = YAML.safe_load(File.read(path))
+    return "#{FILENAME} does not declare a config_asks list" unless data.is_a?(Hash) && data["config_asks"].is_a?(Array)
+
+    nil
+  rescue StandardError => e
+    "#{FILENAME} could not be read: #{e.message}"
+  end
+
+  # All declared entries, or [] if the manifest is missing or malformed. Use
+  # manifest_error alongside this when the difference between "no entries"
+  # and "could not read the manifest" matters (it always does for a health
+  # check or an announcement -- see manifest_error above).
+  def self.load_entries(plastic_home)
+    path = File.join(plastic_home, FILENAME)
+    return [] unless File.exist?(path)
+
+    data = YAML.safe_load(File.read(path)) || {}
+    entries = data["config_asks"]
+    entries.is_a?(Array) ? entries : []
+  rescue StandardError
+    []
+  end
+
+  # Entries whose key is unset in config.yml AND whose id is not dismissed AND
+  # whose agents (if any) include agent_key. Deliberately ignores "introduced"
+  # -- see the schema comment in config_asks.yml for why (retro-fire).
+  #
+  # agent_key: nil means "do not filter by agent" (every entry applies); pass
+  # the caller's actual agent ("claude", "codex", "hermes") to respect an
+  # entry's agents scoping.
+  def self.pending(plastic_home, agent_key = nil)
+    config = load_config(plastic_home)
+    dismissed = Array(config["config_asks_dismissed"])
+
+    load_entries(plastic_home).select do |entry|
+      next false if dismissed.include?(entry["id"])
+      next false unless applies_to_agent?(entry, agent_key)
+
+      value = dig(config, entry["key"].to_s)
+      value.nil? || value == ""
+    end
+  end
+
+  # The exact command that answers one option of one entry.
+  def self.write_config_command(plastic_home, key, value)
+    "ruby #{File.join(plastic_home, "scripts", "write-config")} #{key} #{value}"
+  end
+
+  # The exact command that dismisses one entry ("not now" / keep default).
+  def self.dismiss_command(plastic_home, id)
+    "ruby #{File.join(plastic_home, "scripts", "write-config")} config_asks_dismissed --push #{id}"
+  end
+
+  # An entry with no agents field (or an empty one) applies to every agent.
+  # Otherwise it applies only when agent_key is nil (no filtering requested)
+  # or is present in the entry's agents list.
+  def self.applies_to_agent?(entry, agent_key)
+    scoped = Array(entry["agents"])
+    return true if scoped.empty?
+    return true if agent_key.nil?
+
+    scoped.include?(agent_key)
+  end
+  private_class_method :applies_to_agent?
+
+  def self.load_config(plastic_home)
+    path = File.join(plastic_home, "config.yml")
+    return {} unless File.exist?(path)
+
+    YAML.safe_load(File.read(path)) || {}
+  rescue StandardError
+    {}
+  end
+  private_class_method :load_config
+
+  def self.dig(hash, dotted_key)
+    dotted_key.split(".").reduce(hash) { |acc, k| acc.is_a?(Hash) ? acc[k] : nil }
+  end
+  private_class_method :dig
+end

package/scripts/lib/graph_rebuild.rb

@@ -197,11 +197,17 @@ module GraphRebuild
 
   # Classify a resolved (store, id) relative to the referer, using the live store
   # index to detect dead targets:
-  #   - target id present in the referer's OWN store -> :same_store (collapse to bare)
-  #   - target id present in a DIFFERENT store       -> :cross_store (keep slug:id)
-  #   - target id present NOWHERE                     -> :dead (drop)
+  #   - the store token resolves to no known store          -> :unknown_store (NEVER
+  #     dropped; this is what makes a future discovery miss non-destructive, intent 189 D2)
+  #   - target id present in the referer's OWN known store   -> :same_store (collapse)
+  #   - target id present in a DIFFERENT known store          -> :cross_store (keep slug:id)
+  #   - target id present NOWHERE in a known store            -> :dead (drop)
   def classify(store_tok, bare, referer_store, store_index, original_ref)
     canonical = canonical_store_key(store_tok, store_index)
+    unless known_store?(canonical, store_index)
+      return { status: :unknown_store, ref: original_ref.to_s, store: store_tok }
+    end
+
     if ids_in(store_index, canonical).include?(bare)
       if canonical == referer_store
         { status: :same_store, id: bare }
@@ -213,6 +219,15 @@ module GraphRebuild
     end
   end
 
+  # True iff `canonical` names a store this run actually knows about (it is "global", or a
+  # literal key in `store_index`). A ref whose store token canonicalizes to anything else
+  # has never been discovered by this run, and must be classified :unknown_store, never
+  # :dead: those are different facts (store unknown vs. id absent from a known store) and
+  # only the second one means the ref is genuinely gone.
+  def known_store?(canonical, store_index)
+    canonical == "global" || (store_index || {}).key?(canonical)
+  end
+
   def ids_in(store_index, store_key)
     Array((store_index || {})[store_key])
   end
@@ -225,8 +240,11 @@ module GraphRebuild
   #   relocation_map — from build_relocation_map (spans all stores)
   #   store_index    — { store_key => bare ids present } (spans all stores)
   #
-  # Returns { nodes: <new map>, changes: [ {intent:, kind:, before:, after:} ] }.
-  # kinds: :dedupe, :i3, :repoint, :collapse, :drop, :i1_backlink.
+  # Returns { nodes: <new map>, changes: [ {intent:, kind:, before:, after:} ],
+  #           preserved: [ {intent:, field:, ref:, store:} ] }.
+  # kinds (changes, real mutations only): :dedupe, :i3, :repoint, :collapse, :drop,
+  # :i1_backlink. `preserved` is DIFFERENT: an unknown-store ref left byte-for-byte
+  # unchanged, reported for visibility, never counted as a "change" (nothing mutated).
   #
   # Order is load-bearing (spec Phase 2):
   #   1. dedupe each array order-preserving
@@ -247,6 +265,7 @@ module GraphRebuild
     end
 
     changes = []
+    preserved = []
 
     out.each do |id, edges|
       # 1. dedupe order-preserving
@@ -289,6 +308,11 @@ module GraphRebuild
               changes << { intent: id, kind: :repoint, field: field, before: ref, after: res[:ref] }
             end
             rebuilt << res[:ref]
+          when :unknown_store
+            # NEVER drop: the store is unrecognized, not the id absent from a known store.
+            # Preserve byte-for-byte and report separately from `changes` (nothing mutated).
+            preserved << { intent: id, field: field, ref: ref, store: res[:store] }
+            rebuilt << ref
           when :dead
             changes << { intent: id, kind: :drop, field: field, before: ref, after: nil }
             # dropped: not appended
@@ -323,6 +347,6 @@ module GraphRebuild
       end
     end
 
-    { nodes: out, changes: changes }
+    { nodes: out, changes: changes, preserved: preserved }
   end
 end

package/scripts/lib/hook_registry.rb

@@ -48,6 +48,7 @@ module HookRegistry
         ] },
         { "matcher" => "Write|Edit", "hooks" => [
           { "name" => "savepoint-pre", "status" => "Recording stage start..." },
+          { "name" => "links-gate", "status" => "Checking Links gate..." },
         ] },
         { "matcher" => CREATE_MATCHER, "hooks" => [
           { "name" => "create-gate", "status" => "Checking create gate..." },
@@ -84,7 +85,7 @@ module HookRegistry
   # [{"matcher","hooks":[{"type":"command","command","statusMessage"}]}]}},
   # identical to Claude's shape, string command. Single source of truth (108 D7):
   # any drift from `events` is a bug, pinned by test.
-  CODEX_PRE_HOOKS  = %w[code-gate lock-gate savepoint-pre create-gate].freeze
+  CODEX_PRE_HOOKS  = %w[code-gate lock-gate savepoint-pre links-gate create-gate].freeze
   CODEX_POST_HOOKS = %w[gate-check].freeze
 
   def codex_hooks_json(dispatcher_path:)

package/scripts/lib/installer_core.rb

@@ -251,16 +251,37 @@ class InstallerCore
     puts "  \u{2705} Core files synced (v#{version})"
   end
 
+  # Templates ship in full: every file under templates/ in the repo must reach
+  # ~/.plastic/templates/ on install/update. Derived from Dir.glob so a new
+  # template file added later is registered automatically, closing the
+  # whack-a-mole pattern that hid templates/index.md and templates/project.yml
+  # from every install for five weeks (intent 190).
+  def template_files
+    Dir.glob(File.join(package_root, "templates", "*")).each_with_object({}) do |path, acc|
+      next unless File.file?(path)
+
+      rel = File.join("templates", File.basename(path))
+      acc[rel] = rel
+    end
+  end
+
   # Files copied into ~/.plastic on install/update. Every verb script + the shared lib
   # must be here so the installed ~/.plastic/scripts copy is self-complete (sync-guarded
-  # by install_sync_test).
+  # by install_sync_test). The templates half is glob-derived (template_files above); the
+  # rest stays a hand-written literal.
   def core_files
+    hand_registered_files.merge(template_files)
+  end
+
+  def hand_registered_files
     {
       "PLASTIC.md" => "PLASTIC.md",
       "PLASTIC-reference.md" => "PLASTIC-reference.md",
       "deprecations.yml" => "deprecations.yml",
+      "config_asks.yml" => "config_asks.yml",
       "scripts/folgezettel-id" => "scripts/folgezettel-id",
       "scripts/read-config" => "scripts/read-config",
+      "scripts/write-config" => "scripts/write-config",
       "scripts/select-update-target" => "scripts/select-update-target",
       "scripts/hook-session-start" => "scripts/hook-session-start",
       "scripts/hook-continue" => "scripts/hook-continue",
@@ -271,6 +292,7 @@ class InstallerCore
       "scripts/lib/qmd_hook.rb" => "scripts/lib/qmd_hook.rb",
       "scripts/lib/power_tools.rb" => "scripts/lib/power_tools.rb",
       "scripts/lib/agent_models.rb" => "scripts/lib/agent_models.rb",
+      "scripts/lib/config_asks.rb" => "scripts/lib/config_asks.rb",
       "scripts/lib/release_guard.rb" => "scripts/lib/release_guard.rb",
       "scripts/hook-code-gate" => "scripts/hook-code-gate",
       "scripts/hook-lock-gate" => "scripts/hook-lock-gate",
@@ -296,6 +318,7 @@ class InstallerCore
       "scripts/roadmap-next" => "scripts/roadmap-next",
       "scripts/lib/intent_validator.rb" => "scripts/lib/intent_validator.rb",
       "scripts/lib/graph_rebuild.rb" => "scripts/lib/graph_rebuild.rb",
+      "scripts/lib/store_discovery.rb" => "scripts/lib/store_discovery.rb",
       "scripts/lib/frontmatter_writer.rb" => "scripts/lib/frontmatter_writer.rb",
       "scripts/lib/links_projection.rb" => "scripts/lib/links_projection.rb",
       "scripts/lib/links_section.rb" => "scripts/lib/links_section.rb",
@@ -303,21 +326,21 @@ class InstallerCore
       "scripts/project-links" => "scripts/project-links",
       "scripts/link-suggest" => "scripts/link-suggest",
       "scripts/rebuild-graph" => "scripts/rebuild-graph",
+      "scripts/lib/restore_intent_v1.rb" => "scripts/lib/restore_intent_v1.rb",
+      "scripts/restore-intent-v1" => "scripts/restore-intent-v1",
       "scripts/validate-intent" => "scripts/validate-intent",
       "scripts/new-intent" => "scripts/new-intent",
       "scripts/end-intent" => "scripts/end-intent",
       "scripts/hook-create-gate" => "scripts/hook-create-gate",
+      "scripts/hook-links-gate" => "scripts/hook-links-gate",
+      "scripts/lib/links_gate.rb" => "scripts/lib/links_gate.rb",
       "scripts/lib/apply_patch_envelope.rb" => "scripts/lib/apply_patch_envelope.rb",
       "scripts/codex-hook" => "scripts/codex-hook",
-      "templates/intent.md" => "templates/intent.md",
-      "templates/spec.md" => "templates/spec.md",
-      "templates/plan.md" => "templates/plan.md",
-      "templates/checklist.md" => "templates/checklist.md",
-      "templates/outcome.md" => "templates/outcome.md",
-      "templates/revisions.md" => "templates/revisions.md",
       "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/project_validator.rb" => "scripts/lib/project_validator.rb",
+      "scripts/validate-project" => "scripts/validate-project",
       "scripts/lib/installer_core.rb" => "scripts/lib/installer_core.rb",
       "scripts/lib/preflight.rb" => "scripts/lib/preflight.rb",
       "scripts/install.rb" => "scripts/install.rb",

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