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

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`
 
@@ -238,20 +256,29 @@ hygiene after each intent. Advisory self-check, not hard-verifiable.
 ## Retrieval Gate
 
 A single capability-aware PreToolUse gate enforces retrieval-first routing on the agent's own
-Bash/Read/Grep/Glob calls (and on subagents, since PreToolUse binds them). Detection is binary:
-present means enforce, absent or down means off, with no warning and no advisory tier.
-
-- Store markdown (under a Plastic store) routes to QMD when QMD is present and the index is
-  fresh: the raw grep/find/Read is blocked and you use `qmd search`/`qmd query` (or
-  `scripts/qmd-sync search`) instead. When QMD is present but stale, the read is allowed this
-  turn and a background reindex is fired so the next turn enforces against a fresh index;
-  reindex is never synchronous. When QMD is absent or down, raw reads are allowed.
-- Serena-supported code and data files route to Serena symbolic tools when Serena is present;
-  absent means allowed.
-- Images, binaries, and everything else are allowed.
-- Bypass: append a trailing `# qmd-ok` shell comment to a Bash command for the rare case where
-  QMD is healthy but you genuinely need the raw read. A quoted or echoed occurrence does not
-  bypass. Bypasses are logged.
+Bash/Read/Grep/Glob calls (and on subagents, since PreToolUse binds them). The gate is
+OPERATION-based: it separates searching from reading, and it never stands between you and
+reading something you have already located.
+
+- Only CONTENT SEARCH over a Plastic store is gated. The Grep tool and bash `grep`/`rg`/`ag`
+  whose target is at or under a store route to QMD when QMD is present and the index is fresh:
+  the raw scan is blocked and you use `qmd search`/`qmd query` (or `scripts/qmd-sync search`)
+  instead. When QMD is present but stale, the search is allowed this turn and a background
+  reindex is fired so the next turn enforces against a fresh index; reindex is never
+  synchronous. When QMD is absent, the search is allowed.
+- Reading a known target (the Read tool, bash `cat`/`head`/`tail`) and structural discovery
+  (the Glob tool, bash `find`/`ls`) are always allowed, including over the store. QMD cannot
+  list directories or hand back one specific file, so these are never gated.
+- Code is never hard-gated here. Symbolic code navigation via Serena is a soft prompt mandate
+  (the UserPromptSubmit power-tools hook), not a block: content grep over code is allowed,
+  because Serena navigates symbols and cannot grep arbitrary strings.
+- QMD failure model. Absent or stale degrades to allow (stale also fires the background
+  reindex). A broken QMD, where the freshness probe errors or times out, also fails open, and
+  the hook emits a one-line warning so a degraded QMD is visible rather than silent.
+- Bypass: append a trailing `# qmd-ok` shell comment to a Bash command when you attempted
+  discovery and it did not serve you (no hits, or results that do not answer your need by your
+  reading of the snippets, not their score). A quoted or echoed occurrence does not bypass.
+  Bypasses are logged. The gate enforces that discovery was attempted, never that it succeeded.
 - Scope: only the agent's tool calls. Ruby `File.read` inside a script is invisible to the gate
   and is out of scope by design.
 

package/package.json

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

package/scripts/hook-retrieval-gate

@@ -2,14 +2,19 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-# PreToolUse retrieval gate (intent 84, Lever 2). Reads the tool call (JSON on
-# stdin: tool_name + tool_input), computes capabilities (QMD detect+freshness,
-# Serena detect), delegates the decision to RetrievalGate, and enforces:
+# PreToolUse retrieval gate (intent 84, Lever 2; operation-based redesign 89a).
+# Reads the tool call (JSON on stdin: tool_name + tool_input), computes
+# capabilities (QMD detect + freshness), delegates the decision to RetrievalGate,
+# and enforces:
 #   ALLOW = exit 0 ; BLOCK = exit 2 with reason on stderr (shown to the agent).
 # Fail-open: any parse error, timeout, or unexpected exception exits 0. On the
 # STALE QMD path RetrievalGate fires QmdSync.reindex_async (NEVER synchronous).
 # Binds subagents (PreToolUse hooks apply to subagent tool calls too).
 #
+# Only CONTENT SEARCH over store markdown is gated; reads and structural ops are
+# allowed. Code navigation is a soft prompt mandate (UserPromptSubmit power-tools),
+# not enforced here, so this hook no longer detects Serena.
+#
 # Scope: only the agent's own Bash/Read/Grep/Glob calls. Ruby `File.read` inside
 # scripts is invisible to a PreToolUse hook and is out of scope (no exemptions).
 #
@@ -19,15 +24,14 @@ require "json"
 require "timeout"
 require_relative "lib/retrieval_gate"
 require_relative "lib/qmd_sync"
-require_relative "lib/power_tools"
 
 module RetrievalGateHook
   module_function
 
   # Pure-ish core: capabilities and reindex are injected so this is unit-testable
-  # with no real qmd/serena. Returns [exit_code, stderr_string].
+  # with no real qmd. Returns [exit_code, stderr_string].
   #   stdin: raw PreToolUse JSON
-  #   capabilities: { qmd:, qmd_fresh:, serena: }
+  #   capabilities: { qmd:, qmd_fresh: }
   #   reindex: callable fired on the STALE path
   def run(stdin:, plastic_home:, cwd:, capabilities:, reindex: -> {})
     payload = parse(stdin)
@@ -62,23 +66,33 @@ module RetrievalGateHook
     nil
   end
 
-  # Detect real capabilities for the live executable. A slow `qmd status` cannot
-  # stall a tool call: a Timeout around the freshness probe degrades to "absent
-  # for this turn" (allow, no reindex), staying fail-open and non-blocking.
-  def detect_capabilities(cwd:)
-    qmd = QmdSync.detect
+  # Detect real capabilities for the live executable. Probes are injected so the
+  # three-tier QMD failure model is unit-testable:
+  #   - absent  : QMD not on PATH                 -> allow, no warn.
+  #   - broken  : QMD present but freshness probe  -> tier-b: WARN once, then treat
+  #               raises/times out                   as absent this turn (allow).
+  #   - fresh   : probe returns truthy            -> gate is live.
+  # A slow `qmd status` cannot stall a tool call: a 2s Timeout bounds the probe.
+  def detect_capabilities(cwd:,
+                          detect: -> { QmdSync.detect },
+                          fresh: -> { QmdSync.fresh? },
+                          warn: ->(m) { $stderr.puts(m) })
+    qmd = detect.call
     qmd_fresh = false
     if qmd
-      qmd_fresh = begin
-        Timeout.timeout(2) { QmdSync.fresh? }
+      begin
+        qmd_fresh = Timeout.timeout(2) { fresh.call }
       rescue StandardError
-        # Probe stalled/failed: treat as absent this turn (allow, no reindex).
+        # Tier-b: QMD is present but its freshness probe broke/stalled. Distinct
+        # from QMD being absent — warn so a degraded QMD is visible, then fail open
+        # (allow this turn, no reindex).
+        warn.call("PLASTIC GATE — QMD is present but its freshness probe failed; " \
+                  "allowing this turn without routing search to QMD (check qmd).")
         qmd = false
-        false
+        qmd_fresh = false
       end
     end
-    serena = PowerTools.serena?(cwd: cwd)
-    { qmd: qmd, qmd_fresh: qmd_fresh, serena: serena }
+    { qmd: qmd, qmd_fresh: qmd_fresh }
   end
 
   # Best-effort reindex callable for the STALE path. Resolves the collection from

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/lib/retrieval_gate.rb

@@ -3,62 +3,57 @@
 
 require_relative "bridge"
 
-# RetrievalGate — the single, pure decision for Lever 2 of intent 84.
+# RetrievalGate — the single, pure decision for Lever 2 of intent 84, redesigned
+# operation-based in intent 89a.
 #
 # Given an agent tool call (Bash/Read/Grep/Glob) and injected capability signals,
-# it decides whether to BLOCK the call (returning a redirect-to-QMD/Serena reason
-# String) or ALLOW it (returning nil). All capability and freshness signals are
-# injected by the caller (the hook); this module shells out to nothing, reads no
-# globals, and runs no binaries. Mirrors bridge.rb's decision-fn convention
-# (reason String to block, nil to allow).
+# it decides whether to BLOCK the call (returning a redirect-to-QMD reason String)
+# or ALLOW it (returning nil). All capability/freshness signals are injected by the
+# caller (the hook); this module shells out to nothing, reads no globals, and runs
+# no binaries. Mirrors bridge.rb's decision-fn convention (reason String to block,
+# nil to allow).
 #
-# Classification (per target path):
-#   - store `*.md` (under <plastic_home>/store or .../projects/<slug>/store) -> QMD
-#   - Serena-supported code/data file (NOT a store markdown) -> SERENA
-#   - images / binary / other -> ALLOWED
+# Operation-based policy (intent 89, ## Redesign):
+#   - The gate distinguishes DISCOVERY (content search) from READING a known target.
+#   - Only CONTENT SEARCH over store markdown is hard-gated -> QMD.
+#   - Reading a known target (Read, cat/head/tail) and structural discovery (Glob,
+#     find, ls) are ALWAYS allowed, including over the store.
+#   - Code navigation is a soft prompt MANDATE (PowerTools / UserPromptSubmit), not a
+#     hard gate here. Content grep over code is allowed (Serena cannot grep strings).
 #
-# Capability enforcement is BINARY (no advisory tier):
-#   - QMD class: detected+fresh -> BLOCK; detected+stale -> fire reindex, ALLOW
-#     this turn; absent/down -> ALLOW (no warning).
-#   - SERENA class: detected -> BLOCK; absent -> ALLOW.
+# Content-search vectors (the only ones that can be gated):
+#   - the Grep tool (its `path` search root)
+#   - bash `grep`/`rg`/`ag` (their path args; the first bareword is the PATTERN)
 #
-# Bypass: a TRAILING `# qmd-ok` shell comment on a Bash command (not a substring;
-# a quoted/echoed occurrence does not bypass).
+# QMD enforcement is BINARY (no advisory tier):
+#   - store-md content search: QMD detected+fresh -> BLOCK; detected+stale -> fire
+#     reindex, ALLOW this turn; absent/broken -> ALLOW (the hook warns on broken).
 #
-# Scope: only the agent's own tool calls. Ruby `File.read` inside scripts is
-# invisible to a PreToolUse hook and is explicitly out of scope (no exemptions).
+# Bypass: a TRAILING `# qmd-ok` shell comment on a Bash command (not a substring; a
+# quoted/echoed occurrence does not bypass). It is the auditable seam for "I tried
+# discovery and it did not serve me" (empty, low, or wrongly-scored results).
+#
+# Scope: only the agent's own tool calls. Ruby `File.read` inside scripts is invisible
+# to a PreToolUse hook and is explicitly out of scope (no exemptions).
 module RetrievalGate
   module_function
 
-  # Serena LSP covers many languages incl. JSON/YAML/TOML/Markdown/Ruby. Keep a
-  # small, conservative allowlist of code/data extensions. Markdown is listed but
-  # store markdown is reclassified to QMD before Serena ever sees it.
-  SERENA_EXTENSIONS = %w[
-    rb js jsx ts tsx mjs cjs py go rs java kt scala c h cpp hpp cc
-    cs php rb swift sh bash zsh lua ex exs erl clj sql
-    json yaml yml toml
-  ].freeze
-
-  # Image / binary extensions that are always allowed (plain read is fine).
-  BINARY_EXTENSIONS = %w[
-    png jpg jpeg gif webp svg ico bmp tiff pdf
-    zip gz tar tgz bz2 xz 7z
-    mp3 mp4 mov avi wav flac ogg
-    woff woff2 ttf otf eot
-    bin exe dll so dylib o a class jar wasm
-  ].freeze
-
   # A `# qmd-ok` token that is a real TRAILING shell comment, after stripping a
   # trailing newline. The token must be preceded by whitespace (or start the
-  # command) and run to end-of-string. `echo "# qmd-ok"` does NOT match: the
-  # token there is followed by a closing quote, not end-of-string.
+  # command) and run to end-of-string. `echo "# qmd-ok"` does NOT match: the token
+  # there is followed by a closing quote, not end-of-string.
   BYPASS_RE = /(?:\A|\s)#\s*qmd-ok\s*\z/.freeze
 
+  # Bash utilities that perform CONTENT SEARCH (scan file CONTENT for a pattern).
+  # These are the only bash read-vectors that can be gated; readers (cat/head/tail)
+  # and structural tools (find/ls) are never gated.
+  CONTENT_SEARCH_UTILS = %w[grep rg ag].freeze
+
   # Decide. Returns nil to ALLOW, or a reason String to BLOCK.
-  #   capabilities: { qmd:, qmd_fresh:, serena: } (booleans).
+  #   capabilities: { qmd:, qmd_fresh: } (booleans).
   #   reindex: no-arg callable fired once when a QMD-class target is STALE.
-  # When bypassed, returns nil and (if given) yields :bypass to the optional
-  # block so the caller can log it.
+  # When bypassed, returns nil and (if given) yields :bypass to the optional block
+  # so the caller can log it.
   def decision(tool_name:, tool_input:, plastic_home:, cwd:,
                capabilities:, reindex: -> {})
     targets = extract_targets(tool_name, tool_input, cwd: cwd)
@@ -71,17 +66,14 @@ module RetrievalGate
 
     stale_seen = false
     targets.each do |path|
-      case classify(path, plastic_home: plastic_home)
-      when :qmd
-        if capabilities[:qmd] && capabilities[:qmd_fresh]
-          return qmd_reason(path)
-        elsif capabilities[:qmd] # present but stale
-          stale_seen = true
-        end
-        # absent/down -> allow this target
-      when :serena
-        return serena_reason(path) if capabilities[:serena]
+      next unless classify(path, plastic_home: plastic_home) == :qmd
+
+      if capabilities[:qmd] && capabilities[:qmd_fresh]
+        return qmd_reason(path)
+      elsif capabilities[:qmd] # present but stale
+        stale_seen = true
       end
+      # absent/broken -> allow this target
     end
 
     reindex.call if stale_seen
@@ -90,27 +82,21 @@ module RetrievalGate
 
   # --- classification ---
 
+  # Operation-based: the store tree is the only gated class (content search whose
+  # target is at/under a store routes to QMD). Everything else is allowed.
   def classify(path, plastic_home:)
     return :allow if path.nil? || path.empty?
-    ext = extension(path)
-
-    if store_markdown?(path, plastic_home: plastic_home)
-      return :qmd
-    end
-    return :allow if BINARY_EXTENSIONS.include?(ext)
-    return :serena if SERENA_EXTENSIONS.include?(ext)
-
-    :allow
+    store_path?(path, plastic_home: plastic_home) ? :qmd : :allow
   end
 
-  # A markdown file under the global store or a project store. QMD owns store
-  # markdown even though Serena could also read markdown (QMD wins for the store).
-  def store_markdown?(path, plastic_home:)
-    return false unless %w[md markdown].include?(extension(path))
+  # A path AT or UNDER the global store or a project store. We gate the whole store
+  # tree (not just `*.md`) because a content search root is usually a directory:
+  # grepping the store scans its markdown, which is exactly what QMD should serve.
+  def store_path?(path, plastic_home:)
     abs = absolutize(path)
     home = File.expand_path(plastic_home)
     global = File.join(home, "store")
-    return true if abs.start_with?("#{global}/")
+    return true if abs == global || abs.start_with?("#{global}/")
 
     projects = File.join(home, "projects")
     return false unless abs.start_with?("#{projects}/")
@@ -118,19 +104,14 @@ module RetrievalGate
     tail.length >= 2 && tail[1] == "store"
   end
 
-  def extension(path)
-    File.extname(path.to_s).sub(/\A\./, "").downcase
-  end
-
   def absolutize(path)
     File.absolute_path?(path) ? path : File.expand_path(path)
   end
 
   # --- bypass ---
 
-  # Only Bash commands carry a trailing `# qmd-ok` comment. The token must be a
-  # real trailing comment (BYPASS_RE), so a quoted/echoed occurrence does not
-  # bypass.
+  # Only Bash commands carry a trailing `# qmd-ok` comment. The token must be a real
+  # trailing comment (BYPASS_RE), so a quoted/echoed occurrence does not bypass.
   def bypass?(tool_name, tool_input)
     return false unless tool_name.to_s == "Bash"
     cmd = tool_input.is_a?(Hash) ? tool_input["command"].to_s : ""
@@ -139,40 +120,36 @@ module RetrievalGate
 
   # --- target extraction ---
 
-  # Paths the call reads/scans. Conservative: missing an exotic form is fine;
-  # never flag /dev/null or pure pipes. Read vectors only (this is a READ gate),
-  # not the write vectors bridge.rb already covers.
+  # Paths a CONTENT-SEARCH operation scans. Reads (Read, cat/head/tail) and
+  # structural discovery (Glob, find, ls) are NOT content search -> no targets ->
+  # always allowed. Only the Grep tool and bash grep/rg/ag can be gated. Read
+  # vectors only (this is a READ gate); write vectors are bridge.rb's job.
   def extract_targets(tool_name, tool_input, cwd:)
     input = tool_input.is_a?(Hash) ? tool_input : {}
     case tool_name.to_s
-    when "Read"
-      [input["file_path"]].compact.reject(&:empty?)
-    when "Glob"
-      [input["path"], input["pattern"]].compact.reject { |s| s.to_s.empty? }
     when "Grep"
       # The search root is the target; the query text is not a path.
       [input["path"]].compact.reject { |s| s.to_s.empty? }
     when "Bash"
-      bash_read_targets(input["command"].to_s)
+      bash_search_targets(input["command"].to_s)
     else
+      # Read, Glob, and every other tool: read / structural op -> never gated.
       []
     end
   end
 
-  # READ utilities that take file/dir path arguments. Conservative parse: split
-  # on shell separators, identify the utility, collect its non-flag path args.
-  READ_UTILS = %w[grep rg ag find cat head tail less more bat ls wc nl sort uniq].freeze
-
-  def bash_read_targets(command)
+  # CONTENT-SEARCH path args across a compound command. Conservative: missing an
+  # exotic form is fine; never flag /dev/null or pure pipes.
+  def bash_search_targets(command)
     return [] unless command.is_a?(String) && !command.empty?
     targets = []
     command.split(/[;\n]|&&|\|\||\|/).each do |segment|
-      targets.concat(segment_read_targets(segment))
+      targets.concat(segment_search_targets(segment))
     end
     targets.reject { |t| t.nil? || t.empty? || dev_path?(t) }.uniq
   end
 
-  def segment_read_targets(segment)
+  def segment_search_targets(segment)
     tokens = tokenize(segment)
     return [] if tokens.empty?
 
@@ -180,21 +157,20 @@ module RetrievalGate
     idx = 0
     idx += 1 while tokens[idx] && tokens[idx].include?("=") && tokens[idx] !~ /\A-/
     util = File.basename(tokens[idx].to_s)
-    return [] unless READ_UTILS.include?(util)
+    return [] unless CONTENT_SEARCH_UTILS.include?(util)
 
     args = tokens[(idx + 1)..] || []
-    path_args_for(util, args)
+    path_args_for(args)
   end
 
-  # Collect path-shaped arguments for a read utility. Flags and flag-values are
-  # skipped; for grep/rg the first non-flag bareword is the PATTERN, not a path.
-  def path_args_for(util, args)
-    skip_pattern = %w[grep rg ag].include?(util)
+  # Collect path-shaped arguments for a content-search util. Flags are skipped; the
+  # first non-flag bareword is the PATTERN, not a path.
+  def path_args_for(args)
     paths = []
     pattern_consumed = false
     args.each do |a|
       next if a.start_with?("-")
-      if skip_pattern && !pattern_consumed
+      unless pattern_consumed
         pattern_consumed = true
         next
       end
@@ -225,14 +201,11 @@ module RetrievalGate
   # --- reasons ---
 
   def qmd_reason(path)
-    "retrieval gate: search the store via QMD, not raw grep/Read. " \
-      "Use `qmd search`/`qmd query` over the `plastic-*` collections (or " \
-      "`scripts/qmd-sync search`) instead of reading #{path}. " \
-      "If you genuinely need the raw read, append a trailing `# qmd-ok` to a Bash command."
-  end
-
-  def serena_reason(path)
-    "retrieval gate: navigate code via Serena's symbolic tools (find_symbol / " \
-      "get_symbols_overview / find_referencing_symbols), not raw grep/Read of #{path}."
+    "retrieval gate: search the store via QMD, not a raw content scan. Reading a " \
+      "known file and listing/globbing the store are fine; only CONTENT SEARCH over " \
+      "store markdown routes through QMD. Use `qmd search`/`qmd query` over the " \
+      "`plastic-*` collections (or `scripts/qmd-sync search`) instead of scanning " \
+      "#{path}. If QMD's results do not answer your need (your reading of the " \
+      "snippets, not their score), append a trailing `# qmd-ok` to a Bash command."
   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]
 ```