@zalom/plastic 1.0.0-beta.16 → 1.0.0-beta.17

package/PLASTIC.md

@@ -57,6 +57,24 @@ tags: [plastic, architecture]
   Ordering is mandatory: all `sources` first (top), then all `chain`, frontmatter order
   preserved within each group. Sources never appear at the end. No source/chain tags, no
   sub-grouping. An intent with empty `sources` and `chain` carries the empty-state comment.
+- `## Links` is a DERIVED view, not a place to author links (Convention over Configuration).
+  It equals the projection of `sources` (first) then `chain`. Never hand-write or hand-edit a
+  `## Links` line, and never auto-delete one. The edge lives in the frontmatter graph; the
+  section is regenerated from it (doctor `graph_links_projection` enforces this identity). To
+  add a link, add the frontmatter edge, then reproject.
+- Links are decided by CONTEXT INFLUENCE, not by shared files, shared symbols, or a topic
+  similarity score. The question is whether one intent's context actually informed another.
+  Three tiers:
+  - **sources:** the foundational context that shaped this intent's creation (a split, an idea
+    born during development, a merge). Earns an edge.
+  - **chain:** the context that materially helps DELIVER this intent. This is a HIGH bar: only
+    the genuinely delivery-moving intents, not everything in the same area. Earns an edge,
+    reflected in `## Links`.
+  - **tags:** a loose theme grouping for search. NOT a link. A shared tag is a door INTO the
+    store (filtered discovery), not a pathway BETWEEN two notes.
+  Judging influence is an agent's call, made by reading the candidate's Intent and Context. A
+  script cannot grade it, so `scripts/link-suggest` only gathers candidates with that evidence,
+  records a confirmed edge with a rating and reason, and flags drift.
 - IDs use Luhmann's alternating convention: `1` → `1a` → `1a1` → `1a1a`
 - Multiple branches increment: `1a`, `1b`, `1c`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.0-beta.16",
+  "version": "1.0.0-beta.17",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/lib/installer_core.rb

@@ -223,7 +223,9 @@ class InstallerCore
       "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",

package/scripts/lib/link_suggestions.rb

@@ -0,0 +1,322 @@
+# 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
+#                  line to `link-decisions.md` (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"
+
+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 line to `link-decisions.md` in the subject dir 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
+
+    reader.write(subject[:path], updated)
+    append_decision(subject, target_id, edge, rating, reason, now)
+    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
+
+  # Append one decision line to `link-decisions.md` in the subject's dir, creating the
+  # ledger with a header when absent. Append-only; never rewrites prior lines.
+  def append_decision(subject, target_id, edge, rating, reason, now)
+    ledger = File.join(subject[:dir], "link-decisions.md")
+    stamp = now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+    line = "#{stamp} | #{target_id} | #{edge} | #{rating || "-"} | #{reason || "-"}"
+
+    if reader.exist?(ledger)
+      existing = reader.read(ledger)
+      reader.write(ledger, existing.rstrip + "\n" + line + "\n")
+    else
+      header = "# Link decisions (intent 91 D6): utc | target | edge | rating | reason\n\n"
+      reader.write(ledger, header + line + "\n")
+    end
+  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

package/scripts/link-suggest

@@ -0,0 +1,211 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# link-suggest - support links decided by CONTEXT INFLUENCE (intent 91, D7). Links are
+# NOT graded by a script: whether one intent's context influenced another is a
+# judgement an agent makes by reading the candidate's Intent + Context. This tool
+# gathers candidates with that evidence, records a CONFIRMED edge plus its rating and
+# reason in `link-decisions.md`, and flags drift. It never writes a `## Links` line and
+# never deletes.
+#
+# `## Links` is a DERIVED view of `sources`/`chain` (Convention over Configuration).
+# Tiers, by context influence:
+#   sources - the foundational context that shaped this intent's creation.
+#   chain   - the context that materially helps DELIVER this intent. HIGH bar.
+#   tags    - loose theme grouping for search. Not a link.
+#
+# Usage:
+#   link-suggest <subject_id> [--store-dir PATH] [--plastic-home PATH]
+#   link-suggest <subject_id> --record <target_id> --edge <sources|chain>
+#                --rating <high|medium|low> --reason "..." --confirm
+#   link-suggest --help
+#
+# Default (no --record) prints candidates WITH their Intent+Context plus any drift, and
+# writes nothing. --record without --confirm prints what would happen and writes
+# nothing. --edge is explicit and required (sources is decided by origin, never
+# inferred); --rating is required when --edge is chain.
+
+require_relative "lib/link_suggestions"
+
+module LinkSuggestCLI
+  module_function
+
+  DEFAULT_HOME = File.join(Dir.home, ".plastic")
+
+  USAGE = <<~TXT
+    Usage:
+      link-suggest <subject_id> [--store-dir PATH] [--plastic-home PATH]
+      link-suggest <subject_id> --record <target_id> --edge <sources|chain> \\
+                   --rating <high|medium|low> --reason "..." --confirm
+      link-suggest --help
+
+    Links are decided by context influence, judged by an agent reading each
+    candidate's Intent + Context. This tool only gathers candidates with that
+    evidence, records a confirmed edge plus its rating/reason in link-decisions.md,
+    and flags drift. It never writes a ## Links line and never deletes.
+
+    --edge is explicit and required (sources is decided by origin, never inferred).
+    --rating is required when --edge is chain. Without --confirm, nothing is written.
+  TXT
+
+  def parse(argv)
+    opts = { home: DEFAULT_HOME, store_dir: nil, subject: nil, help: false,
+             record: nil, edge: nil, rating: nil, reason: nil, confirm: false }
+    i = 0
+    while i < argv.length
+      case argv[i]
+      when "--help", "-h" then opts[:help] = true; i += 1
+      when "--plastic-home" then opts[:home] = argv[i + 1]; i += 2
+      when "--store-dir" then opts[:store_dir] = argv[i + 1]; i += 2
+      when "--record" then opts[:record] = argv[i + 1]; i += 2
+      when "--edge" then opts[:edge] = (argv[i + 1] || "").to_sym; i += 2
+      when "--rating" then opts[:rating] = argv[i + 1]; i += 2
+      when "--reason" then opts[:reason] = argv[i + 1]; i += 2
+      when "--confirm" then opts[:confirm] = true; i += 1
+      else
+        opts[:subject] ||= argv[i]
+        i += 1
+      end
+    end
+    opts[:store_dir] ||= File.join(opts[:home], "store")
+    opts
+  end
+
+  # Print the discovery candidates with their Intent + Context evidence, plus drift.
+  def report(tool, subject, out: $stdout)
+    nodes = tool.load_nodes
+    unless nodes.key?(subject)
+      out.puts "link-suggest: no intent #{subject.inspect} in #{tool.store_dir}"
+      return 1
+    end
+
+    cands = tool.gather(subject, nodes: nodes)
+    out.puts "Candidates for #{subject} (discovery only; judge influence by reading context):"
+    if cands.empty?
+      out.puts "  (none)"
+    else
+      cands.each { |c| print_candidate(c, out) }
+    end
+
+    flaws = tool.drift(subject, nodes: nodes)
+    out.puts "Drift for #{subject}:"
+    if flaws.empty?
+      out.puts "  (none)"
+    else
+      flaws.each { |f| out.puts "  [drift] #{f.detail}" }
+    end
+    0
+  end
+
+  def print_candidate(cand, out)
+    out.puts "  - #{cand.id}  #{cand.label}"
+    out.puts "    Intent:  #{excerpt(cand.intent)}" unless cand.intent.empty?
+    out.puts "    Context: #{excerpt(cand.context)}" unless cand.context.empty?
+  end
+
+  # A one-paragraph excerpt of a section, for scannable evidence.
+  def excerpt(text, limit: 280)
+    flat = text.to_s.gsub(/\s+/, " ").strip
+    flat.length > limit ? "#{flat[0, limit]}..." : flat
+  end
+
+  def do_record(tool, opts, out: $stdout)
+    if opts[:edge].nil? || !%i[sources chain].include?(opts[:edge])
+      out.puts "link-suggest: --record requires --edge sources|chain (explicit, never inferred)."
+      return 1
+    end
+    if opts[:edge] == :chain && (opts[:rating].nil? || !LinkSuggestions::RATINGS.include?(opts[:rating]))
+      out.puts "link-suggest: --rating high|medium|low is required for a chain edge."
+      return 1
+    end
+
+    unless opts[:confirm]
+      out.puts "Would record #{opts[:edge]} edge #{opts[:subject]} -> #{opts[:record]} " \
+               "(rating #{opts[:rating] || "-"}, reason: #{opts[:reason] || "-"}). " \
+               "Re-run with --confirm to write. Nothing written."
+      return 0
+    end
+
+    wrote = tool.record_edge(opts[:subject], opts[:record],
+                             edge: opts[:edge], rating: opts[:rating],
+                             reason: opts[:reason], confirm: true)
+    if wrote
+      out.puts "Recorded #{opts[:edge]} edge #{opts[:subject]} -> #{opts[:record]} " \
+               "and appended to link-decisions.md. Reproject with scripts/project-links."
+      return 0
+    end
+    out.puts "No edge written (edge may already exist, or intent missing)."
+    0
+  end
+
+  def run(argv, out: $stdout)
+    opts = parse(argv)
+    if opts[:help]
+      out.puts USAGE
+      return 0
+    end
+    unless opts[:subject]
+      out.puts USAGE
+      return 1
+    end
+
+    tool = LinkSuggestions.new(store_dir: opts[:store_dir], finder: build_finder(opts[:store_dir]))
+
+    return do_record(tool, opts, out: out) if opts[:record]
+
+    report(tool, opts[:subject], out: out)
+  end
+
+  # The real candidate-finder, wired here (not in the lib): use QMD when available,
+  # else fall back to the lib's cheap family/tag/adjacent net. Discovery only.
+  def build_finder(store_dir)
+    qmd = qmd_finder(store_dir)
+    qmd || LinkSuggestions::FamilyTagFinder.new
+  end
+
+  # A QMD-backed finder when the `qmd` (or qmd-sync) CLI is on PATH. It seeds discovery
+  # from the subject's intent line, unions the hits with the cheap fallback net, and
+  # returns ids present in the store. Any failure falls back silently. Discovery only,
+  # never a grade.
+  def qmd_finder(_store_dir)
+    return nil unless qmd_available?
+
+    fallback = LinkSuggestions::FamilyTagFinder.new
+    lambda do |subject_id, nodes|
+      base = fallback.call(subject_id, nodes)
+      subject = nodes[subject_id]
+      return base unless subject
+
+      hits = qmd_search_ids(subject[:label], nodes)
+      (base + hits).uniq.reject { |id| id == subject_id }
+    end
+  end
+
+  def qmd_available?
+    %w[qmd qmd-sync].any? { |c| system("command -v #{c} >/dev/null 2>&1") }
+  rescue StandardError
+    false
+  end
+
+  # Best-effort: ask qmd-sync for related text and map any id-shaped tokens back to
+  # store ids. Never raises; returns [] on any trouble.
+  def qmd_search_ids(query, nodes)
+    return [] if query.to_s.strip.empty?
+
+    out = `ruby #{File.join(Dir.home, ".plastic", "scripts", "qmd-sync")} search #{shell_quote(query)} 2>/dev/null`
+    return [] if out.nil? || out.empty?
+
+    out.scan(/\b([0-9]+[a-z0-9]*)\b/).flatten.uniq.select { |id| nodes.key?(id) }
+  rescue StandardError
+    []
+  end
+
+  def shell_quote(str)
+    "'#{str.to_s.gsub("'", "'\\\\''")}'"
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  exit LinkSuggestCLI.run(ARGV)
+end

package/skills/creating-intent/SKILL.md

@@ -62,12 +62,18 @@ Having a "parent" in mind does NOT automatically mean branch. Choose by meaning:
     direct-ascendant provenance (D1).
   - **Merely related to / inspired by another intent** (it did NOT come out of that
     intent's lifecycle): carry NO `--sources`. Record the relation on the PREDECESSOR's
-    `chain` instead, and mirror it as a `[[id]]` wikilink in `## Links` (the
-    related-but-not-spawned rule).
+    `chain` instead (the related-but-not-spawned rule); the `## Links` section follows
+    from that edge, you do not write it by hand.
 - **Rule of thumb:** if the intent could exist without its parent, make it a root; only set
   `--sources` when it was genuinely created from / emerged from that intent's lifecycle.
   Topic similarity alone is not a `sources` edge.
 
+`## Links` is a DERIVED view of `sources`/`chain`. Never hand-write a `## Links` line; add the
+frontmatter edge and reproject. Links are decided by context influence (a `chain` edge has a high
+bar: the candidate's context must materially help deliver this intent), not by shared files or a
+similarity score. To gather candidates with their context and record an edge, use the
+`plastic-linking-intents` skill and `scripts/link-suggest`.
+
 ### 3. Determine Intent Properties
 
 Ask or infer from context:

package/skills/linking-intents/SKILL.md

@@ -6,34 +6,70 @@ description: Use when creating connections between intents, the user says "link"
 # Linking Intents
 
 ## When to Use
-- During intent creation (automatic — ask about related intents)
+- During intent creation (automatic: ask about related intents)
 - User says "link", "connect", "relates to"
 - Agent discovers a relationship between intents during work
 
-## Connection Types (Ranked by Strength)
+## Discovery and ranking are separate
 
-### 1. Direct Links (Strongest)
-Explicit wikilinks in the `## Links` section. Bidirectional — add to both intents.
+Two distinct steps, do not conflate them:
 
-```markdown
-## Links
-- [[1a]] — research this plan is based on
-```
+1. **Discovery** (finding candidate related intents) may use any tool: grep, find, ripgrep,
+   or QMD/Serena when present (QMD-first per the project rule). Discovery casts a wide net.
+2. **Ranking** the candidates is a CONTEXT-INFLUENCE judgement: read each candidate's `## Intent`
+   and `## Context` and ask whether that context actually informed this intent. Ranking is NOT a
+   structural metric (no shared-file or shared-symbol grading: on intent 90, matching whole files
+   flagged 35 intents because ~20 touch `bridge.rb`). It is NOT a similarity score either (QMD
+   relevance measures topic proximity, not influence). A script cannot make this call; an agent
+   does.
+
+## The three tiers (by context influence)
+
+- **sources:** the foundational context that shaped this intent's CREATION (a split, an idea born
+  during development, a merge). Earns an edge. Decided by origin, never inferred.
+- **chain:** the context that materially helps DELIVER this intent. HIGH bar: only the genuinely
+  delivery-moving intents, not everything in the same area. Earns an edge, reflected in `## Links`.
+  Worked example (intent 90): 79 created it so 79 is a source; 80 deferred the exact fix 90 makes,
+  so its context directly helps delivery and 80 is chain; 49/66/73 are same-area background, so
+  they get a shared tag and no link.
+- **tags:** loose theme grouping for search. NOT a link.
+
+**Timing.** The influence judgement happens at What/Why (and during upkeep), guided by this rule.
+It does not wait for code to exist; it is reasoning over the candidate's context, not over a diff.
+
+**Record the call.** For every edge an agent adds, store a rating (high / medium / low) plus a
+one-line reason in `link-decisions.md` in the intent dir. Keep it out of frontmatter (graph only)
+and out of the `## Links` label (which is projected), so the audit trail never breaks the
+projection identity.
+
+## `## Links` is derived (never author it by hand)
+
+`## Links` is a DERIVED view of `sources` then `chain`, not a place to write links. Never
+hand-write a `## Links` line, and never auto-delete one. To add a link, add the frontmatter
+edge (below), then let the projection regenerate the section (`scripts/project-links`).
+
+Run `scripts/link-suggest <id>` to gather candidate intents WITH each one's Intent and Context (the
+evidence you judge influence on) and to flag drift (a `## Links` line with no frontmatter edge
+behind it). To record a confirmed edge plus its rating and reason, run it with
+`--record <id> --edge <sources|chain> --rating <high|medium|low> --reason "..." --confirm`. It never
+grades influence itself, never writes an edge without `--confirm`, and never deletes.
+
+## Connection Types (the frontmatter edges)
 
-### 2. Sources (Backward)
+### 1. Sources (Backward)
 The `sources` array in frontmatter. The direct ascendant(s) this intent was created from / emerged from the lifecycle of (formation, not topic similarity), backward links to the work it was built out of:
 ```yaml
 sources: ["1a", "1a2"]
 ```
 
-### 3. Chain (Forward)
+### 2. Chain (Forward)
 The `chain` array in frontmatter. What this intent spawned AND related-but-not-spawned successors it leads to, forward links to children, follow-on, and related work:
 ```yaml
 chain: ["1b1", "1b2"]
 ```
 
-### 4. Tags (Weakest)
-Shared tags in frontmatter enable filtered discovery. Use `project-<name>` tags for project membership.
+### 3. Tags (for discovery, not links)
+Shared tags in frontmatter enable filtered discovery. Use `project-<name>` tags for project membership. A shared tag is a loose theme grouping: it earns NO edge.
 ```yaml
 tags: [plastic, project-reddit-kb]
 ```