@zalom/plastic 1.3.0 → 1.4.1

package/scripts/lib/installer_core.rb

@@ -17,9 +17,10 @@ class InstallerCore
   DEFAULT_PLASTIC_HOME = File.join(Dir.home, ".plastic")
 
   DEFAULT_AGENTS = [
-    { key: "claude", name: "Claude Code", dir: File.join(Dir.home, ".claude"), flag: "--claude" },
+    { key: "claude", name: "Claude Code", dir: File.join(Dir.home, ".claude"), flag: "--claude",
+      skill_prefix: "/" },
     { key: "codex", name: "Codex CLI", dir: File.join(Dir.home, ".agents"),
-      home_dir: File.join(Dir.home, ".codex"), flag: "--codex" },
+      home_dir: File.join(Dir.home, ".codex"), flag: "--codex", skill_prefix: "$" },
     { key: "hermes", name: "Hermes", dir: File.join(Dir.home, ".hermes"), flag: "--hermes" },
   ].freeze
 
@@ -43,7 +44,8 @@ class InstallerCore
     - The full conventions live in ~/.plastic/PLASTIC.md. Read it and follow it exactly.
       It is generated and overwritten on Plastic updates, so never edit it.
     - Operational procedures are installed as skills under ~/.agents/skills/ (each
-      plastic-<name>/SKILL.md). Use them for the lifecycle work they describe.
+      plastic-<name>/SKILL.md). Invoke one explicitly as $plastic-<name> (for example
+      $plastic-doctor), or let Codex pick one implicitly by matching its description.
     - Intents, specs, plans, checklists, and outcomes live under ~/.plastic/, never in
       the project tree.
 
@@ -175,7 +177,7 @@ class InstallerCore
     return ["claude"] unless input.tty?
 
     puts "Which agents should Plastic register for?\n\n"
-    agents.each_with_index { |a, i| puts "  #{i + 1}. #{a[:name]} (#{a[:dir]})" }
+    agents.each_with_index { |a, i| puts "  #{i + 1}. #{a[:name]} (#{a[:home_dir] || a[:dir]})" }
     puts "  #{agents.size + 1}. All"
     puts
 
@@ -251,16 +253,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 +294,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 +320,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 +328,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",
@@ -397,12 +422,44 @@ class InstallerCore
     (data["files"] || {}).keys
   end
 
+  # Per-agent registration probe (intent 198, D7 follow-up). `installed?` in
+  # install.rb only answers "is Plastic core installed at all", which cannot
+  # tell two harnesses apart: once core is present, install.rb's old gate
+  # refused to add ANY new harness, even one that had never been touched. This
+  # asks the narrower, correct question, "has Plastic already registered
+  # files for THIS agent", using the signal already tracked for prune-on-update:
+  # the per-agent manifest (manifest_path_for). A missing manifest file, or a
+  # manifest whose "files" list is empty (write_manifest still writes one when
+  # nothing was installed), both mean nothing is registered for this agent yet.
+  # An unknown key is never "installed" (fail toward proceeding, since a caller
+  # that already validated the key gets its own "Unknown agent" result from
+  # install_for_agent).
+  def agent_installed?(key)
+    config = agent_config(key)
+    return false unless config
+    !manifest_files(manifest_path_for(key, config)).empty?
+  end
+
   def install_for_agent(key, force, argv: [], input: $stdin, reinstall: false)
     config = agent_config(key)
     return { agent: config[:name], success: false, reason: "Unknown agent" } unless config
 
-    unless File.directory?(config[:dir])
-      return { agent: config[:name], success: false, reason: "#{config[:dir]} not found \u{2014} #{config[:name]} not installed?" }
+    # Presence probe (intent 198, Decision D1): an agent that declares its own
+    # home directory (Codex, home_dir: ~/.codex) is checked THERE, because
+    # config[:dir] (~/.agents) is the shared cross-tool skills root, not
+    # anything Codex itself creates. A fresh Codex install has no ~/.agents
+    # yet, so testing config[:dir] aborted a genuinely-present Codex. Claude
+    # and Hermes declare no home_dir, so presence_dir resolves to config[:dir]
+    # exactly as before and their behavior is unchanged. The failure message
+    # reuses the same resolved directory, so it always names the directory
+    # actually tested. install_codex still needs config[:dir] to exist by the
+    # time it writes skills; install_skills_flat and generate_codex_agents
+    # already FileUtils.mkdir_p their own nested paths under config[:dir] and
+    # config[:home_dir], so a fresh install creates it as a side effect (no
+    # separate top-level mkdir_p is required here).
+    presence_dir = config[:home_dir] || config[:dir]
+    unless File.directory?(presence_dir)
+      return { agent: config[:name], success: false, reason: "#{presence_dir} not found, #{config[:name]} not installed?" }
     end
 
     # Capture the prior manifest so we can prune files that no longer ship

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