@zalom/plastic 1.0.0-beta.8 → 1.0.0

package/scripts/lib/installer_core.rb

@@ -6,6 +6,8 @@ require "yaml"
 require "fileutils"
 require "digest"
 require "time"
+require_relative "hook_registry"
+require_relative "agent_models"
 
 # Shared installer machinery, instantiable with injected package root / store / agent
 # map so the verb scripts (install/update/uninstall/versions) and their tests can run
@@ -159,6 +161,37 @@ class InstallerCore
     nums.select { |n| n >= 1 && n <= agents.size }.map { |n| agents[n - 1][:key] }
   end
 
+  # Resolve whether install should keep the user's existing statusline or switch it
+  # to Plastic's. Pure function of (settings file, argv, input, reinstall): no writes,
+  # so it stays fully unit-testable apart from merge_claude_hooks.
+  def statusline_choice(settings_path, argv: [], input: $stdin, reinstall: false)
+    existing_command = read_json_safe(settings_path)&.dig("statusLine", "command").to_s
+    return :plastic if existing_command.empty?
+    return :plastic if existing_command.include?("plastic-")
+
+    idx = argv.index("--statusline")
+    flag = idx && argv[idx + 1]
+    return flag.to_sym if %w[keep plastic].include?(flag)
+
+    return :keep if reinstall
+    return prompt_statusline(input: input) if input.tty?
+
+    :keep
+  end
+
+  def prompt_statusline(input: $stdin)
+    return :keep unless input.tty?
+
+    puts "An existing statusline was found in your settings.\n\n"
+    puts "  1. Keep my statusline (Plastic will not change it)"
+    puts "  2. Switch to Plastic's statusline"
+    puts
+    print "Select (1 or 2, Enter to keep): "
+    answer = input.gets&.strip
+
+    answer == "2" ? :plastic : :keep
+  end
+
   # --- Distribution phase ---
 
   def distribute(mode)
@@ -195,6 +228,7 @@ class InstallerCore
   def core_files
     {
       "PLASTIC.md" => "PLASTIC.md",
+      "PLASTIC-reference.md" => "PLASTIC-reference.md",
       "deprecations.yml" => "deprecations.yml",
       "scripts/folgezettel-id" => "scripts/folgezettel-id",
       "scripts/read-config" => "scripts/read-config",
@@ -203,17 +237,37 @@ class InstallerCore
       "scripts/hook-continue" => "scripts/hook-continue",
       "scripts/hook-future-intent-check" => "scripts/hook-future-intent-check",
       "scripts/hook-gate-check" => "scripts/hook-gate-check",
+      "scripts/hook-savepoint-pre" => "scripts/hook-savepoint-pre",
       "scripts/hook-qmd-search" => "scripts/hook-qmd-search",
       "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/hook-code-gate" => "scripts/hook-code-gate",
+      "scripts/hook-lock-gate" => "scripts/hook-lock-gate",
       "scripts/hook-bash-gate" => "scripts/hook-bash-gate",
+      "scripts/hook-retrieval-gate" => "scripts/hook-retrieval-gate",
+      "scripts/lib/retrieval_gate.rb" => "scripts/lib/retrieval_gate.rb",
       "scripts/hook-auto-arm" => "scripts/hook-auto-arm",
       "scripts/lib/bridge.rb" => "scripts/lib/bridge.rb",
+      "scripts/lib/lock.rb" => "scripts/lib/lock.rb",
+      "scripts/plastic-lock" => "scripts/plastic-lock",
+      "scripts/lib/hook_registry.rb" => "scripts/lib/hook_registry.rb",
+      "scripts/agent-report" => "scripts/agent-report",
+      "scripts/lib/insights.rb" => "scripts/lib/insights.rb",
+      "scripts/lib/worktree.rb" => "scripts/lib/worktree.rb",
       "scripts/lib/boot_banner.rb" => "scripts/lib/boot_banner.rb",
+      "scripts/lib/dashboard_banner.rb" => "scripts/lib/dashboard_banner.rb",
       "scripts/lib/qmd_sync.rb" => "scripts/lib/qmd_sync.rb",
       "scripts/qmd-sync" => "scripts/qmd-sync",
       "scripts/lib/intent_validator.rb" => "scripts/lib/intent_validator.rb",
+      "scripts/lib/graph_rebuild.rb" => "scripts/lib/graph_rebuild.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",
+      "scripts/lib/link_suggestions.rb" => "scripts/lib/link_suggestions.rb",
+      "scripts/project-links" => "scripts/project-links",
+      "scripts/link-suggest" => "scripts/link-suggest",
+      "scripts/rebuild-graph" => "scripts/rebuild-graph",
       "scripts/validate-intent" => "scripts/validate-intent",
       "scripts/new-intent" => "scripts/new-intent",
       "scripts/hook-create-gate" => "scripts/hook-create-gate",
@@ -222,10 +276,12 @@ class InstallerCore
       "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/installer_core.rb" => "scripts/lib/installer_core.rb",
+      "scripts/lib/preflight.rb" => "scripts/lib/preflight.rb",
       "scripts/install.rb" => "scripts/install.rb",
       "scripts/update.rb" => "scripts/update.rb",
       "scripts/uninstall.rb" => "scripts/uninstall.rb",
@@ -298,7 +354,7 @@ class InstallerCore
     (data["files"] || {}).keys
   end
 
-  def install_for_agent(key, force)
+  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
 
@@ -311,7 +367,7 @@ class InstallerCore
     old_files = manifest_files(manifest_path_for(key, config))
 
     result = case key
-             when "claude" then install_claude(config, force)
+             when "claude" then install_claude(config, force, argv: argv, input: input, reinstall: reinstall)
              when "codex" then install_codex(config, force)
              when "hermes" then install_hermes(config, force)
              end
@@ -340,7 +396,7 @@ class InstallerCore
     removed
   end
 
-  def install_claude(config, force)
+  def install_claude(config, force, argv: [], input: $stdin, reinstall: false)
     hooks_dir = File.join(config[:dir], "hooks")
     skills_root = File.join(config[:dir], "skills")
     plastic_dir = File.join(config[:dir], "plastic")
@@ -371,7 +427,7 @@ class InstallerCore
     installed += install_skills_flat(skills_source, skills_root) if File.directory?(skills_source)
 
     # Copy agent role files into <dir>/agents (manifest-tracked, pruned on update)
-    installed += install_agents(File.join(config[:dir], "agents"))
+    installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides)
 
     # Write VERSION
     version_file = File.join(plastic_dir, "VERSION")
@@ -383,7 +439,8 @@ class InstallerCore
 
     # Merge hooks + statusline into settings.json (no plugin registration)
     settings_path = File.join(config[:dir], "settings.json")
-    merge_claude_hooks(settings_path)
+    choice = statusline_choice(settings_path, argv: argv, input: input, reinstall: reinstall)
+    merge_claude_hooks(settings_path, choice: choice)
 
     # Write manifest
     manifest_path = File.join(plastic_dir, "manifest.json")
@@ -396,7 +453,7 @@ class InstallerCore
     installed = []
     skills_source = File.join(package_root, "skills")
     installed += install_skills_flat(skills_source, File.join(config[:dir], "skills")) if File.directory?(skills_source)
-    installed += install_agents(File.join(config[:dir], "agents"))
+    installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides)
 
     write_manifest(installed, File.join(config[:dir], "plastic-manifest.json"))
     { agent: config[:name], success: true, files: installed.size }
@@ -406,7 +463,7 @@ class InstallerCore
     installed = []
     skills_source = File.join(package_root, "skills")
     installed += install_skills_flat(skills_source, File.join(config[:dir], "skills")) if File.directory?(skills_source)
-    installed += install_agents(File.join(config[:dir], "agents"))
+    installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides)
 
     write_manifest(installed, File.join(config[:dir], "plastic-manifest.json"))
     { agent: config[:name], success: true, files: installed.size }
@@ -439,18 +496,51 @@ class InstallerCore
   # equivalents). Returns the installed destination paths so callers can append
   # them to `installed` before write_manifest (manifest + prune are then automatic).
   # No-op safe: returns [] when the package has no agents dir or it is empty.
-  def install_agents(agents_root)
+  def install_agents(agents_root, models: {})
     sources = Dir.glob(File.join(package_root, "agents", "*.md"))
     return [] if sources.empty?
 
     FileUtils.mkdir_p(agents_root)
     sources.map do |src|
       dest = File.join(agents_root, File.basename(src))
-      FileUtils.cp(src, dest)
+      basename = File.basename(src, ".md")
+      override = models[basename]
+      if override
+        File.write(dest, rewrite_model_line(File.read(src), override))
+      else
+        FileUtils.cp(src, dest)
+      end
       dest
     end
   end
 
+  # Rewrite the single top-level `model:` line in a YAML frontmatter block.
+  # Only the frontmatter (between the first two `---` fences) is touched.
+  def rewrite_model_line(content, model)
+    content.sub(/^model:[^\n]*$/, "model: #{model}")
+  end
+
+  # Resolve per-agent model overrides for this install: project config (when a
+  # project dir is known) overlaid on global config. Defaults are NOT included,
+  # so unconfigured agents keep their shipped frontmatter.
+  def agent_model_overrides(project_dir = nil)
+    global_config = load_config_yaml(File.join(plastic_home, "config.yml"))
+    project_config =
+      if project_dir
+        load_config_yaml(File.join(project_dir, ".plastic_store", "config.yml"))
+      else
+        {}
+      end
+    AgentModels.override_map(project_config: project_config, global_config: global_config)
+  end
+
+  def load_config_yaml(path)
+    return {} unless File.exist?(path)
+    YAML.safe_load(File.read(path)) || {}
+  rescue StandardError
+    {}
+  end
+
   # --- Legacy plugin migration ---
 
   # Earlier versions registered Plastic as a local marketplace plugin
@@ -516,7 +606,7 @@ class InstallerCore
 
   # --- settings.json merge (read-modify-write, never clobber) ---
 
-  def merge_claude_hooks(settings_path)
+  def merge_claude_hooks(settings_path, choice: :plastic)
     settings = read_json_safe(settings_path) || {}
     return if settings.nil?
 
@@ -525,55 +615,9 @@ class InstallerCore
 
     purge_stale_plastic_hooks(hooks)
 
-    plastic_hooks = {
-      "SessionStart" => {
-        "matcher" => "",
-        "hooks" => [
-          { "type" => "command", "command" => "#{hook_dir}/plastic-session-start", "statusMessage" => "Loading Plastic context..." },
-          { "type" => "command", "command" => "#{hook_dir}/plastic-check-update", "statusMessage" => "" },
-        ],
-      },
-      "PreCompact" => {
-        "matcher" => "",
-        "hooks" => [
-          { "type" => "command", "command" => "#{hook_dir}/plastic-savepoint", "statusMessage" => "Saving Plastic intent state..." },
-        ],
-      },
-      # PreToolUse carries TWO plastic groups with distinct matchers: the
-      # code-gate (Write|Edit|NotebookEdit) and the create-gate (Write only, intent
-      # 60b). A single group cannot carry two matchers, so this event maps to a
-      # LIST of groups; the merge loop appends each (idempotent because the purge
-      # pass removes all prior plastic groups first).
-      "PreToolUse" => [
-        {
-          "matcher" => "Write|Edit|NotebookEdit",
-          "hooks" => [
-            { "type" => "command", "command" => "#{hook_dir}/plastic-code-gate", "statusMessage" => "Checking lifecycle gate..." },
-          ],
-        },
-        {
-          "matcher" => "Write",
-          "hooks" => [
-            { "type" => "command", "command" => "#{hook_dir}/plastic-create-gate", "statusMessage" => "Checking create gate..." },
-          ],
-        },
-      ],
-      "PostToolUse" => {
-        "matcher" => "Write|Edit",
-        "hooks" => [
-          { "type" => "command", "command" => "#{hook_dir}/plastic-gate-check", "statusMessage" => "Checking lifecycle gates..." },
-        ],
-      },
-      "UserPromptSubmit" => {
-        "matcher" => "",
-        "hooks" => [
-          { "type" => "command", "command" => "#{hook_dir}/plastic-continue", "statusMessage" => "Checking for continue..." },
-          { "type" => "command", "command" => "#{hook_dir}/plastic-future-intent-check", "statusMessage" => "Checking future intents..." },
-          { "type" => "command", "command" => "#{hook_dir}/plastic-auto-arm", "statusMessage" => "Checking auto mode..." },
-          { "type" => "command", "command" => "#{hook_dir}/plastic-qmd-search", "statusMessage" => "Searching QMD..." },
-        ],
-      },
-    }
+    # Single source of truth (intent 108, D7): registrations live in
+    # HookRegistry; this merge only translates them into settings.json.
+    plastic_hooks = HookRegistry.claude_settings_hooks(hook_dir: hook_dir)
 
     plastic_hooks.each do |event, group|
       hooks[event] ||= []
@@ -604,7 +648,7 @@ class InstallerCore
       File.write(File.join(cache_dir, "original-statusline.json"), JSON.pretty_generate(existing_status))
     end
 
-    settings["statusLine"] = { "type" => "command", "command" => "#{hook_dir}/plastic-statusline" }
+    settings["statusLine"] = { "type" => "command", "command" => "#{hook_dir}/plastic-statusline" } if choice == :plastic
 
     # No plugin/marketplace registration: skills are flat personal skills
     # (plastic-<name>/) discovered directly from ~/.claude/skills.

package/scripts/lib/link_suggestions.rb

@@ -0,0 +1,319 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# LinkSuggestions - support links decided by CONTEXT INFLUENCE (intent 91, D7), not
+# by shared files, shared symbols, or a topic-similarity score. A script cannot judge
+# whether one intent's context influenced another (that is reasoning over meaning), so
+# this helper does NOT grade. It only:
+#
+#   - gather:      DISCOVERY. Find candidate intents (via an injected candidate-finder)
+#                  and surface each candidate's `## Intent` + `## Context` as the
+#                  EVIDENCE an agent reads to judge influence.
+#   - record_edge: record a CONFIRMED `sources`/`chain` frontmatter edge AND append a
+#                  dated line to the subject intent file's `## Insights` section
+#                  carrying (utc, target, edge, rating, reason).
+#                  Append-only, frontmatter block only, never a `## Links` line,
+#                  never a delete. A no-op without confirm: true.
+#   - drift:       flag any `## Links` wikilink with no matching frontmatter edge.
+#
+# Two systems frame this:
+#   - System for Brain: links are tiered by context influence (sources = foundational
+#     context that shaped creation; chain = the genuinely delivery-moving context, a
+#     HIGH bar; tags = loose theme grouping, not a link). The influence judgement is
+#     made by an agent, not here.
+#   - System for Work (Convention over Configuration): `## Links` is a derived view of
+#     `sources`/`chain`. This helper never authors a `## Links` line and never deletes.
+#
+# Design rules: all collaborators are injected via the constructor (the store dir, a
+# filesystem reader, AND a candidate-finder). No eval, no ENV / global config seam.
+# Reuses IntentValidator.parse_frontmatter; does NOT touch LinksProjection /
+# LinksSection / project-links / doctor.
+
+require "time"
+require_relative "intent_validator"
+require_relative "insights"
+
+class LinkSuggestions
+  # One discovery candidate plus the evidence an agent reads to judge influence.
+  Candidate = Struct.new(:id, :basename, :label, :intent, :context, keyword_init: true)
+
+  # A drift finding: a `## Links` ref with no matching `sources`/`chain` edge.
+  Drift = Struct.new(:ref, :detail, keyword_init: true)
+
+  RATINGS = %w[high medium low].freeze
+
+  # A minimal default filesystem reader. Injected so tests can substitute an
+  # in-memory map; the production path reads real files. No global state.
+  class DiskReader
+    def directory?(path)
+      File.directory?(path)
+    end
+
+    def children(path)
+      Dir.children(path)
+    end
+
+    def exist?(path)
+      File.exist?(path)
+    end
+
+    def read(path)
+      File.read(path)
+    end
+
+    def write(path, content)
+      File.write(path, content)
+    end
+  end
+
+  # Default candidate-finder: a cheap discovery net (NOT a grade) over the loaded
+  # nodes - candidates that share a non-project tag, share a `sources` parent/family,
+  # or sit at an adjacent id. The CLI may inject a QMD-backed finder instead. Either
+  # way this is DISCOVERY ONLY; influence is judged later by an agent.
+  class FamilyTagFinder
+    def call(subject_id, nodes)
+      subject = nodes[subject_id]
+      return [] unless subject
+
+      nodes.keys.select do |other_id|
+        next false if other_id == subject_id
+
+        other = nodes[other_id]
+        shares_tag?(subject, other) || shares_family?(subject, other) ||
+          adjacent_id?(subject_id, other_id)
+      end
+    end
+
+    private
+
+    def shares_tag?(subject, other)
+      !(link_tags(subject) & link_tags(other)).empty?
+    end
+
+    def link_tags(node)
+      node[:tags].reject { |t| t.start_with?("project-") }
+    end
+
+    def shares_family?(subject, other)
+      return true unless (subject[:sources] & other[:sources]).empty?
+
+      subject[:sources].include?(other[:id]) || other[:sources].include?(subject[:id])
+    end
+
+    # Adjacent ids (discovery hint only): equal non-numeric prefix with integers
+    # differing by 1 (9<->10, 99<->100, 90<->91), or a letter successor at the same
+    # depth (66a<->66b). This is NOT a grade; it only widens the candidate net.
+    def adjacent_id?(a, b)
+      return false if a == b || a.empty? || b.empty?
+
+      ma = a.match(/\A(.*?)(\d+)\z/)
+      mb = b.match(/\A(.*?)(\d+)\z/)
+      return (ma[2].to_i - mb[2].to_i).abs == 1 if ma && mb && ma[1] == mb[1]
+
+      return false unless a.length == b.length
+
+      a[0..-2] == b[0..-2] && a[-1].match?(/[a-z]/) && b[-1].match?(/[a-z]/) &&
+        (a[-1].succ == b[-1] || b[-1].succ == a[-1])
+    end
+  end
+
+  # store_dir - the directory holding `id--slug/` intent folders for ONE store.
+  # reader    - injected filesystem collaborator (DiskReader by default).
+  # finder    - injected candidate-finder responding to #call(subject_id, nodes).
+  def initialize(store_dir:, reader: DiskReader.new, finder: FamilyTagFinder.new)
+    @store_dir = store_dir
+    @reader = reader
+    @finder = finder
+  end
+
+  attr_reader :store_dir, :reader, :finder
+
+  # Load every intent in the store as a node Hash keyed by id:
+  #   { id => { id:, basename:, label:, path:, dir:, sources:[], chain:[], tags:[],
+  #             links_refs:[], intent:, context: } }
+  def load_nodes
+    nodes = {}
+    return nodes unless reader.directory?(store_dir)
+
+    reader.children(store_dir).reject { |e| e.start_with?(".") }.sort.each do |entry|
+      dir = File.join(store_dir, entry)
+      next unless reader.directory?(dir)
+
+      md = File.join(dir, "#{entry}.md")
+      next unless reader.exist?(md)
+
+      content = reader.read(md)
+      fm = IntentValidator.parse_frontmatter_text(content)
+      next unless fm.is_a?(Hash) && fm["id"]
+
+      id = fm["id"].to_s
+      body = IntentValidator.body_of(content)
+      nodes[id] = {
+        id: id,
+        basename: entry,
+        label: fm["intent"].to_s.strip,
+        path: md,
+        dir: dir,
+        sources: Array(fm["sources"]).map(&:to_s),
+        chain: Array(fm["chain"]).map(&:to_s),
+        tags: Array(fm["tags"]).map(&:to_s),
+        links_refs: links_refs(body),
+        intent: section_text(body, "Intent"),
+        context: section_text(body, "Context"),
+      }
+    end
+    nodes
+  end
+
+  # DISCOVERY. The candidate intents for `subject_id`, each carrying its Intent +
+  # Context as the evidence an agent reads to judge influence. No grading. Sorted by
+  # natural id order for stable output.
+  def gather(subject_id, nodes: load_nodes)
+    return [] unless nodes.key?(subject_id)
+
+    ids = finder.call(subject_id, nodes)
+    ids.uniq.sort_by { |id| natural_key(id) }.filter_map do |id|
+      node = nodes[id]
+      next unless node
+
+      Candidate.new(id: id, basename: node[:basename], label: node[:label],
+                    intent: node[:intent], context: node[:context])
+    end
+  end
+
+  # Record a single CONFIRMED edge from `subject_id` to `target_id`:
+  #   1. append `target_id` to the subject's frontmatter `sources` or `chain`;
+  #   2. append a dated line to the subject's `## Insights` section capturing
+  #      {utc, target, edge, rating, reason}.
+  # Append-only, frontmatter block only. NEVER writes a `## Links` line, NEVER
+  # deletes. A no-op (returns false) without confirm: true, so a default run mutates
+  # nothing. Returns true when it wrote, false when it declined or the edge existed.
+  def record_edge(subject_id, target_id, edge:, rating: nil, reason: nil,
+                  confirm: false, now: Time.now, nodes: load_nodes)
+    return false unless confirm
+    return false unless %i[sources chain].include?(edge)
+
+    subject = nodes[subject_id]
+    return false unless subject
+    return false if subject[edge].include?(target_id)
+
+    content = reader.read(subject[:path])
+    updated = add_frontmatter_ref(content, edge.to_s, target_id)
+    return false if updated == content
+
+    final = append_link_insight(updated, target_id, edge, rating, reason, now)
+    reader.write(subject[:path], final)
+    true
+  end
+
+  # DRIFT. The `## Links` refs on `subject_id` with no matching `sources`/`chain`
+  # frontmatter edge behind them. Fence-skipping is honored so a `[[id]]` inside an
+  # example code block is not flagged.
+  def drift(subject_id, nodes: load_nodes)
+    subject = nodes[subject_id]
+    return [] unless subject
+
+    edges = (subject[:sources] + subject[:chain]).map { |r| bare_ref(r) }
+    subject[:links_refs].reject { |r| edges.include?(bare_ref(r)) }.map do |ref|
+      Drift.new(ref: ref,
+                detail: "`## Links` references #{ref} with no sources/chain edge behind it")
+    end
+  end
+
+  private
+
+  # Insert one dated link-decision line at the bottom of the subject intent file's
+  # `## Insights` section (96 D3: link rationale lives IN the intent file, never a side
+  # file). Reuses the blessed Insights writer (intent 82) for section insertion; carries
+  # the five fields (utc, target, edge, rating, reason) as a readable line under the 82
+  # exact-timestamp prefix. Returns the augmented content for the single caller write.
+  def append_link_insight(content, target_id, edge, rating, reason, now)
+    prefix = "#{now.utc.iso8601} · Link · link-suggest"
+    text = "#{edge} edge to #{target_id} (rating #{rating || "-"}): #{reason || "-"}"
+    Insights.with_entry(content, "#{prefix} — #{text}")
+  end
+
+  # Natural sort key for ids so 2 sorts before 10 and 14a groups with 14.
+  def natural_key(id)
+    id.scan(/\d+|[a-z]+/).map { |part| part.match?(/\d/) ? [0, part.to_i, ""] : [1, 0, part] }
+  end
+
+  # Strip a `store:` prefix from a ref so a cross-store and same-store form compare.
+  def bare_ref(ref)
+    ref.to_s.include?(":") ? ref.to_s.split(":", 2).last : ref.to_s
+  end
+
+  # Extract bare-id wikilink refs from a body's `## Links` section. Matches
+  # `[[<id>--<slug>|...]]` and `[[<store>:<id>--<slug>|...]]`, yielding the bare id.
+  # Reads only the Links section so example fences elsewhere are not scanned.
+  def links_refs(body)
+    section = section_text(body, "Links")
+    return [] if section.empty?
+
+    section.scan(/\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/).filter_map do |match|
+      t = bare_ref(match.first.strip)
+      id = t.split("--", 2).first
+      id unless id.nil? || id.empty?
+    end.uniq
+  end
+
+  # The text under the first `## <heading>` heading, up to the next `## ` heading. A
+  # deliberately small reader since we only need the section content. Fence lines are
+  # skipped so a `## Links` (or any heading) inside an example block is ignored.
+  def section_text(body, heading)
+    lines = body.to_s.lines
+    out = []
+    capture = false
+    in_fence = false
+    lines.each do |line|
+      stripped = line.strip
+      if stripped.start_with?("```")
+        in_fence = !in_fence
+        next
+      end
+      next if in_fence
+
+      if stripped == "## #{heading}"
+        capture = true
+        next
+      end
+      break if capture && stripped.start_with?("## ")
+
+      out << line if capture
+    end
+    out.join.strip
+  end
+
+  # Append a ref to a frontmatter array (`sources` or `chain`), creating the key if
+  # absent. Touches ONLY the frontmatter block; the body (including `## Links`) is
+  # left byte-identical. Inline-flow arrays (`key: ["a", "b"]`) are extended in place;
+  # an absent key is inserted before the closing `---`. Never deletes.
+  def add_frontmatter_ref(content, key, ref)
+    return content unless content.start_with?("---")
+
+    parts = content.split("---", 3)
+    return content if parts.length < 3
+
+    fm = parts[1]
+    line_re = /^#{Regexp.escape(key)}:\s*(.*)$/
+    if fm =~ line_re
+      current = Regexp.last_match(1).strip
+      new_line = extend_flow_array(key, current, ref)
+      fm = fm.sub(line_re, new_line)
+    else
+      fm = fm.rstrip + "\n#{key}: [\"#{ref}\"]\n"
+    end
+    "---#{fm}---#{parts[2]}"
+  end
+
+  def extend_flow_array(key, current, ref)
+    if current.empty? || current == "[]"
+      %(#{key}: ["#{ref}"])
+    elsif current.start_with?("[") && current.end_with?("]")
+      inner = current[1..-2].strip
+      inner.empty? ? %(#{key}: ["#{ref}"]) : %(#{key}: [#{inner}, "#{ref}"])
+    else
+      %(#{key}: ["#{ref}"])
+    end
+  end
+end