@zalom/plastic 1.0.0-beta.7 → 1.0.0-beta.9

package/scripts/lib/links_section.rb

@@ -0,0 +1,207 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "intent_validator"
+
+# LinksSection — pure, minimal, style-preserving rewrite of ONLY the `## Links`
+# section of an intent file's content string (intent 72). Mirrors the discipline of
+# FrontmatterWriter: pure (no file IO, no eval, no global/ENV state), and returns
+# the original content UNCHANGED when nothing changed (idempotency).
+#
+# `## Links` is canonically the LAST sanctioned section
+# (IntentValidator::SANCTIONED_SECTIONS = Intent, Context, Outcome, Insights,
+# Links), and real intents put it last. So a file with an existing `## Links` has
+# its section replaced in place (from the heading to the next top-level `## `
+# heading or EOF), and a file WITHOUT a `## Links` gets one appended at end-of-body,
+# separated by exactly one blank line, preserving the body's trailing-newline shape.
+#
+# FENCE AWARENESS (intent 72 corruption fix): a `## Links` heading INSIDE a fenced
+# code block (``` or ~~~, possibly with an info string like ```markdown) is part of
+# an EXAMPLE, not a real section. All section scanning here IGNORES headings inside
+# fences and only ever targets the REAL `## Links` section (outside any fence). The
+# section end is the next `## ` heading that is ALSO outside a fence, so a replace
+# never consumes or unbalances a code fence. If more than one REAL `## Links`
+# heading exists, #rewrite raises AmbiguousLinks rather than guess.
+#
+# Frontmatter is NEVER touched: the leading `---`...`---` block is preserved
+# byte-for-byte and only the body is rebuilt.
+module LinksSection
+  module_function
+
+  HEADING = "## Links"
+
+  # A fence delimiter: ``` or ~~~ (any length >= 3), optional leading whitespace,
+  # optional info string (e.g. ```markdown). Mirrors CommonMark fenced-code rules
+  # closely enough for intent bodies.
+  FENCE_RE = /\A\s*(`{3,}|~{3,})/
+
+  # Raised when a body has more than one REAL `## Links` heading outside any fence;
+  # the tool must fail loud rather than guess which one to rewrite.
+  class AmbiguousLinks < StandardError
+    def initialize(count)
+      super("found #{count} real `## Links` headings outside code fences; refusing to guess")
+    end
+  end
+
+  # PURE. Replace (or insert) the REAL `## Links` section in `content` with
+  # `section_text` (the canonical block from LinksProjection.section, which begins
+  # with the `## Links` heading line and ends with a single trailing newline).
+  # Returns the new content, or the original when nothing changed. Raises
+  # AmbiguousLinks when more than one real `## Links` heading exists.
+  def rewrite(content, section_text)
+    return content unless content.is_a?(String)
+
+    fm, body = split_frontmatter(content)
+    new_body = rewrite_body(body, section_text)
+    updated = "#{fm}#{new_body}"
+    updated == content ? content : updated
+  end
+
+  # Split content into [frontmatter_with_delimiters, body]. When there is no
+  # frontmatter block, the frontmatter part is "" and the whole content is the
+  # body. The frontmatter part is preserved byte-for-byte by the caller.
+  def split_frontmatter(content)
+    return ["", content] unless content.start_with?("---")
+
+    parts = content.split("---", 3)
+    return ["", content] if parts.length < 3
+
+    ["---#{parts[1]}---", parts[2]]
+  end
+
+  # Rewrite ONLY the REAL `## Links` section within the body text.
+  def rewrite_body(body, section_text)
+    bounds = links_bounds(body)
+    if bounds
+      replace_section(body, section_text, bounds)
+    else
+      insert_section(body, section_text)
+    end
+  end
+
+  # PURE. Locate the REAL `## Links` section (fence-aware). Returns
+  # [start_index, end_index] line indices into body.lines, where start_index is the
+  # `## Links` heading line and end_index is the index of the next out-of-fence
+  # `## ` heading (or lines.length at EOF). Returns nil when there is no real
+  # `## Links` heading. Raises AmbiguousLinks when more than one exists.
+  def links_bounds(body)
+    lines = body.to_s.lines
+    starts = real_links_heading_indices(lines)
+    return nil if starts.empty?
+    raise AmbiguousLinks, starts.length if starts.length > 1
+
+    start = starts.first
+    stop = next_out_of_fence_heading(lines, start + 1)
+    [start, stop]
+  end
+
+  # PURE. Indices of every `## Links` heading line that is OUTSIDE any code fence.
+  # Accepts a body String or an Array of lines.
+  def real_links_heading_indices(body_or_lines)
+    lines = body_or_lines.is_a?(Array) ? body_or_lines : body_or_lines.to_s.lines
+    indices = []
+    in_fence = false
+    fence_marker = nil
+    lines.each_with_index do |line, i|
+      if (m = fence_open_close(line, in_fence, fence_marker))
+        in_fence = m[:in_fence]
+        fence_marker = m[:marker]
+        next
+      end
+      indices << i if !in_fence && line.rstrip == HEADING
+    end
+    indices
+  end
+
+  # PURE. Index of the first `## ` heading at or after `from` that is OUTSIDE any
+  # code fence. Returns lines.length when none (EOF). Fence state is recomputed
+  # from the top so nested example fences after the real heading are respected.
+  def next_out_of_fence_heading(lines, from)
+    in_fence = false
+    fence_marker = nil
+    lines.each_with_index do |line, i|
+      if (m = fence_open_close(line, in_fence, fence_marker))
+        in_fence = m[:in_fence]
+        fence_marker = m[:marker]
+        next
+      end
+      return i if i >= from && !in_fence && line.start_with?("## ")
+    end
+    lines.length
+  end
+
+  # PURE. Given the current fence state, decide whether `line` is a fence delimiter
+  # and return the new state, or nil when the line is not a fence delimiter.
+  # An opening fence records its marker family (` or ~); a closing fence must use a
+  # marker of the SAME family and carry no info string.
+  def fence_open_close(line, in_fence, fence_marker)
+    m = line.match(FENCE_RE)
+    return nil unless m
+
+    marker = m[1]
+    family = marker[0] # "`" or "~"
+    if in_fence
+      # A closing fence uses the same family, length >= the opener, no info string.
+      rest = line.sub(FENCE_RE, "").strip
+      if family == fence_marker && rest.empty?
+        { in_fence: false, marker: nil }
+      else
+        # A delimiter of the OTHER family (or an info-string line) inside a fence is
+        # literal content, not a fence event.
+        nil
+      end
+    else
+      { in_fence: true, marker: family }
+    end
+  end
+
+  # True iff the body has a REAL (out-of-fence) `## Links` heading. Used by callers
+  # to classify regenerate-vs-add without re-deriving fence state.
+  def links_heading?(body)
+    !real_links_heading_indices(body.to_s.lines).empty?
+  end
+
+  # Replace the REAL `## Links` section (the [start, stop] line bounds) with
+  # `section_text`, preserving everything before the heading and after the section
+  # byte-for-byte (including any fenced example that lives BEFORE the real section).
+  def replace_section(body, section_text, bounds)
+    lines = body.lines
+    start, stop = bounds
+    before = lines[0...start].join
+    tail = (lines[stop..] || [])
+
+    # `section_text` already ends with exactly one newline. When there is trailing
+    # content (another section follows), separate the block from it with one blank
+    # line; otherwise the section ends the body.
+    block = tail.empty? ? section_text : "#{section_text}\n"
+    "#{before}#{block}#{tail.join}"
+  end
+
+  # Append a `## Links` section at end-of-body, after the last existing section,
+  # separated by exactly one blank line, preserving the body's trailing newline.
+  def insert_section(body, section_text)
+    trimmed = body.to_s.sub(/\s+\z/, "")
+    if trimmed.empty?
+      # An empty body (no sections) just becomes the section.
+      section_text
+    else
+      "#{trimmed}\n\n#{section_text}"
+    end
+  end
+
+  # PURE. Extract the REAL `## Links` section text (fence-aware), normalized to the
+  # canonical block shape the projection emits: heading line + entry lines + a
+  # single trailing newline. Returns "" when there is no real section. Shared by
+  # the IO shell's audit and the doctor drift check so all three agree on the
+  # location. Raises AmbiguousLinks when more than one real heading exists.
+  def extract_section(body)
+    bounds = links_bounds(body)
+    return "" if bounds.nil?
+
+    start, stop = bounds
+    lines = body.to_s.lines
+    section = lines[(start + 1)...stop].join.sub(/\n+\z/, "\n")
+    section = "" if section.strip.empty?
+    "#{HEADING}\n#{section}"
+  end
+end

package/scripts/new-intent

@@ -26,6 +26,9 @@ require "fileutils"
 require "date"
 require_relative "lib/bridge"
 require_relative "lib/intent_validator"
+require_relative "lib/graph_rebuild"
+require_relative "lib/links_projection"
+require_relative "lib/links_section"
 
 # --- Explicit flag parsing (no eval, no global injection) ------------------
 
@@ -106,25 +109,119 @@ def add_to_chain(file_path, new_id)
   File.write(file_path, ["", new_fm, parts[2]].join("---"))
 end
 
-# Append a wikilink line under the file's `## Links` section, idempotently.
-def append_link(file_path, link_line)
-  return unless File.exist?(file_path)
-  content = File.read(file_path)
-  return if content.include?(link_line)
+# Derive [plastic_home, referer_store_key] from a store directory path so the
+# cross-store resolver (shared with project-links and the doctor check) can be
+# built. A global store is `<home>/store` (key "global"); a project store is
+# `<home>/projects/<slug>/store` (key "project:<slug>"). Returns
+# [nil, "global"] only if the layout is unrecognized, in which case Links
+# projection falls back to single-store resolution rooted at this store.
+def store_context(store)
+  store = File.expand_path(store)
+  parent = File.dirname(store)               # `<home>` or `<home>/projects/<slug>`
+  if File.basename(store) == "store" && File.basename(File.dirname(parent)) == "projects"
+    slug = File.basename(parent)
+    home = File.dirname(File.dirname(parent)) # strip projects/<slug>
+    [home, "project:#{slug}"]
+  elsif File.basename(store) == "store"
+    [parent, "global"]                        # `<home>/store`
+  else
+    [parent, "global"]
+  end
+end
+
+# The in-scope stores under `plastic_home`, each { key:, store: }. Mirrors
+# project-links/RebuildGraph#stores so cross-store resolution spans the family.
+def family_stores(plastic_home)
+  list = []
+  global_store = File.join(plastic_home, "store")
+  list << { key: "global", store: global_store } if File.directory?(global_store)
+  %w[plastic knowdb].each do |slug|
+    store = File.join(plastic_home, "projects", slug, "store")
+    list << { key: "project:#{slug}", store: store } if File.directory?(store)
+  end
+  list
+end
+
+# Build the cross-store maps the LinksProjection resolver needs:
+#   store_index    => { store_key => [bare ids] }
+#   node_index     => { store_key => { id => { basename:, label: } } }
+#   relocation_map => from GraphRebuild.build_relocation_map over every INDEX.md
+# `fallback_store` is the store the new intent lives in; it is always included so
+# resolution works even for a brand-new store with no INDEX.md yet.
+def build_cross_store_maps(plastic_home, fallback_store_key, fallback_store_dir)
+  stores = family_stores(plastic_home)
+  # Ensure the fallback store is represented even if family discovery missed it.
+  unless stores.any? { |s| s[:key] == fallback_store_key }
+    stores << { key: fallback_store_key, store: fallback_store_dir }
+  end
+
+  store_index = Hash.new { |h, k| h[k] = [] }
+  node_index = Hash.new { |h, k| h[k] = {} }
+  index_texts = {}
+
+  stores.each do |s|
+    next unless File.directory?(s[:store])
+
+    Dir.children(s[:store]).reject { |e| e.start_with?(".") }.sort.each do |entry|
+      dir = File.join(s[:store], entry)
+      next unless File.directory?(dir)
+
+      md = File.join(dir, "#{entry}.md")
+      next unless File.exist?(md)
 
-  lines = content.lines
-  idx = lines.index { |l| l.strip == "## Links" }
-  return unless idx
+      fm = IntentValidator.parse_frontmatter(md)
+      next unless fm.is_a?(Hash) && fm["id"]
 
-  insert_at = lines.length
-  ((idx + 1)...lines.length).each do |j|
-    if lines[j].strip.start_with?("## ")
-      insert_at = j
-      break
+      id = fm["id"].to_s
+      store_index[s[:key]] << id
+      node_index[s[:key]][id] = { basename: entry, label: fm["intent"].to_s.strip }
     end
+
+    idx = File.join(File.dirname(s[:store]), "INDEX.md")
+    index_texts[s[:key]] = File.read(idx) if File.exist?(idx)
+  end
+
+  relocation_map = GraphRebuild.build_relocation_map(index_texts)
+  { store_index: store_index, node_index: node_index, relocation_map: relocation_map }
+end
+
+# Re-project ONE intent file's `## Links` as the canonical I5 projection of its
+# OWN frontmatter sources+chain, using the shared cross-store resolver. Writes the
+# file only if the section changed (idempotent). Born-canonical: a fresh root with
+# no edges gets the empty-state comment; the fence-aware rewriter touches only the
+# real `## Links` section. Returns true on success, false when the intent could
+# not be read or a ref was unresolvable (left unwritten, never a guessed link).
+def project_links_for(file_path, referer_store_key, maps)
+  return false unless File.exist?(file_path)
+
+  content = File.read(file_path)
+  fm = IntentValidator.parse_frontmatter_text(content)
+  return false unless fm.is_a?(Hash)
+
+  resolve = lambda do |ref|
+    LinksProjection.resolve_ref_projection(
+      ref,
+      referer_store: referer_store_key,
+      relocation_map: maps[:relocation_map],
+      store_index: maps[:store_index],
+      node_index: maps[:node_index]
+    )
+  end
+
+  begin
+    section_text = LinksProjection.section(
+      sources: Array(fm["sources"]).map(&:to_s),
+      chain: Array(fm["chain"]).map(&:to_s),
+      resolve: resolve
+    )
+    updated = LinksSection.rewrite(content, section_text)
+  rescue LinksProjection::UnresolvedRef, LinksSection::AmbiguousLinks => e
+    warn "new-intent: could not project ## Links for #{File.basename(file_path)}: #{e.message}"
+    return false
   end
-  lines.insert(insert_at, "#{link_line}\n")
-  File.write(file_path, lines.join)
+
+  File.write(file_path, updated) if updated != content
+  true
 end
 
 def main(argv)
@@ -176,8 +273,9 @@ def main(argv)
   # 4a. I1 reciprocity: write the child's id into EACH source intent's frontmatter
   # `chain` (the formative-reciprocity backlink), for BOTH the `--parent` and the
   # `--sources` path. `sources` is the redundant-explicit set from step 3 (it already
-  # folds in `--parent`). Scope boundary: 68 fixes ONLY the frontmatter `chain`
-  # backlink; the `## Links` wikilink projection for the `--sources` path is intent 72.
+  # folds in `--parent`). Collect the touched source files so their `## Links` can be
+  # re-projected once the chain edges are on disk.
+  source_files = []
   sources.each do |src_id|
     next if src_id.nil? || src_id.empty?
 
@@ -186,19 +284,22 @@ def main(argv)
 
     src_file = File.join(src_dir, "#{File.basename(src_dir)}.md")
     add_to_chain(src_file, id)
+    source_files << src_file
   end
 
-  # 4b. Reciprocal `## Links` wikilinks: forward link to parent + back-reference in
-  # the parent (kept parent-only; the `--sources` path's wikilink is intent 72's scope).
-  if opts[:parent] && !opts[:parent].empty?
-    parent_id = opts[:parent]
-    append_link(intent_file, "- [[#{parent_id}]]")
-    parent_dir = Dir.glob(File.join(store, "#{parent_id}--*")).find { |d| File.directory?(d) }
-    if parent_dir
-      parent_file = File.join(parent_dir, "#{File.basename(parent_dir)}.md")
-      append_link(parent_file, "- [[#{id}]]")
-    end
-  end
+  # 4b. Canonical `## Links` projection (intent 72): born-canonical, drift PREVENTED
+  # at the source. Build the cross-store resolver maps AFTER the chain backlinks are
+  # written, then project the NEW intent's Links from its own frontmatter (sources at
+  # birth, chain empty) and RE-project each source/parent's Links (it just gained the
+  # new id in its chain). The fence-aware rewriter and the resolved-target dedup are
+  # the same ones project-links and the doctor check use, so a freshly created intent
+  # and its sources both PASS graph_links_projection. A no-source root gets the
+  # canonical empty-state comment.
+  plastic_home, referer_store_key = store_context(store)
+  maps = build_cross_store_maps(plastic_home, referer_store_key, store)
+
+  project_links_for(intent_file, referer_store_key, maps)
+  source_files.uniq.each { |sf| project_links_for(sf, referer_store_key, maps) }
 
   # 5. Sentinel placeholders for each lifecycle file. The sentinel is the FIRST
   # line; the rendered template body follows so the file is a usable starting

package/scripts/project-links

@@ -0,0 +1,287 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# project-links — project each intent's corrected sources/chain graph into its
+# canonical I5 `## Links` section, store-wide across the global, plastic, and
+# knowdb stores (intent 72). Deterministic and idempotent: a second run over a
+# projected store changes zero files. Touches ONLY the `## Links` section of each
+# intent file; frontmatter and every other section stay byte-identical.
+#
+# Usage:
+#   project-links [--plastic-home PATH] [--dry-run] [--audit-path PATH]
+#
+# Pure-Ruby (no bash). The pure logic lives in lib/links_projection.rb and
+# lib/links_section.rb; this shell does only discovery, IO, and reporting. It reads
+# frontmatter (it NEVER writes frontmatter, that is intent 49's domain) and the
+# on-disk `id--slug` directory basenames to build the cross-store resolver.
+# Never pushes ~/.plastic (no git ops here).
+
+require "time"
+require "fileutils"
+
+require_relative "lib/intent_validator"
+require_relative "lib/graph_rebuild"
+require_relative "lib/links_projection"
+require_relative "lib/links_section"
+
+class ProjectLinks
+  DEFAULT_HOME = File.join(Dir.home, ".plastic")
+
+  # The 72 intent dir audit destination (relative to plastic_home).
+  DEFAULT_AUDIT_REL =
+    "projects/plastic/store/72--links-graph-projection/resources/audit--links-projection.md"
+
+  def initialize(plastic_home: DEFAULT_HOME, dry_run: false, audit_path: nil)
+    @plastic_home = plastic_home
+    @dry_run = dry_run
+
+    # A dry run must NOT stomp the canonical audit (humans run --dry-run to review
+    # the plan). With no explicit --audit-path, a dry run writes a `.dry-run.md`
+    # sibling, leaving the canonical real-run audit untouched. An explicit
+    # --audit-path is always honored verbatim (tests inject it). Mirrors
+    # RebuildGraph's discipline exactly.
+    canonical = File.join(plastic_home, DEFAULT_AUDIT_REL)
+    @audit_path =
+      if audit_path
+        audit_path
+      elsif dry_run
+        canonical.sub(/\.md\z/, ".dry-run.md")
+      else
+        canonical
+      end
+  end
+
+  attr_reader :plastic_home, :dry_run, :audit_path
+
+  # The three in-scope stores, each as { key:, root:, store:, index: }.
+  def stores
+    list = []
+    global_store = File.join(plastic_home, "store")
+    if File.directory?(global_store)
+      list << { key: "global", root: plastic_home, store: global_store,
+                index: File.join(plastic_home, "INDEX.md") }
+    end
+
+    %w[plastic knowdb].each do |slug|
+      root = File.join(plastic_home, "projects", slug)
+      store = File.join(root, "store")
+      next unless File.directory?(store)
+
+      list << { key: "project:#{slug}", root: root, store: store,
+                index: File.join(root, "INDEX.md") }
+    end
+    list
+  end
+
+  # { id => { sources:, chain:, basename:, label:, path: } } for one store.
+  def load_nodes(store_dir)
+    nodes = {}
+    Dir.children(store_dir).reject { |e| e.start_with?(".") }.sort.each do |entry|
+      dir = File.join(store_dir, entry)
+      next unless File.directory?(dir)
+
+      md = File.join(dir, "#{entry}.md")
+      next unless File.exist?(md)
+
+      fm = IntentValidator.parse_frontmatter(md)
+      next unless fm.is_a?(Hash) && fm["id"]
+
+      nodes[fm["id"].to_s] = {
+        sources: Array(fm["sources"]).map(&:to_s),
+        chain: Array(fm["chain"]).map(&:to_s),
+        basename: entry, # the on-disk `id--slug` directory name
+        label: fm["intent"].to_s.strip,
+        path: md,
+      }
+    end
+    nodes
+  end
+
+  def run
+    store_list = stores
+    nodes_by_store = {}
+    index_texts = {}
+    store_index = {}
+    node_index = {}
+
+    store_list.each do |s|
+      key = s[:key]
+      nodes_by_store[key] = load_nodes(s[:store])
+      index_texts[key] = File.exist?(s[:index]) ? File.read(s[:index]) : ""
+      store_index[key] = nodes_by_store[key].keys
+      node_index[key] = nodes_by_store[key].transform_values do |v|
+        { basename: v[:basename], label: v[:label] }
+      end
+    end
+
+    relocation_map = GraphRebuild.build_relocation_map(index_texts)
+
+    results = {}
+    store_list.each do |s|
+      key = s[:key]
+      results[key] = project_store(
+        key, nodes_by_store[key],
+        relocation_map: relocation_map, store_index: store_index, node_index: node_index
+      )
+    end
+
+    emit_audit(store_list, results)
+    results
+  end
+
+  # Project every intent in ONE store. Returns
+  # { entries: [ {id:, status:, before:, after:, error:} ], counts: {...} }.
+  def project_store(referer_store, nodes, relocation_map:, store_index:, node_index:)
+    entries = []
+    nodes.each do |id, node|
+      resolve = ->(ref) do
+        LinksProjection.resolve_ref_projection(
+          ref, referer_store: referer_store,
+               relocation_map: relocation_map, store_index: store_index, node_index: node_index
+        )
+      end
+
+      content = File.read(node[:path])
+
+      begin
+        had_links = LinksSection.links_heading?(IntentValidator.body_of(content))
+        section_text = LinksProjection.section(
+          sources: node[:sources], chain: node[:chain], resolve: resolve
+        )
+        updated = LinksSection.rewrite(content, section_text)
+      rescue LinksProjection::UnresolvedRef, LinksSection::AmbiguousLinks => e
+        entries << { id: id, status: :failed, error: e.message }
+        next
+      end
+
+      if updated == content
+        entries << { id: id, status: :unchanged }
+        next
+      end
+
+      status = had_links ? :regenerated : :added
+      File.write(node[:path], updated) unless dry_run
+      entries << { id: id, status: status,
+                   before: extract_links(content), after: section_text }
+    end
+
+    counts = entries.each_with_object(Hash.new(0)) { |e, h| h[e[:status]] += 1 }
+    { entries: entries, counts: counts }
+  end
+
+  # Pull the current REAL `## Links` section text (fence-aware) from a file's
+  # content, for the audit sample. Returns "" when absent. Delegates to the shared
+  # LinksSection.extract_section so the audit, the rewriter, and the doctor check
+  # all agree on the section location (and never match a heading inside an example
+  # code fence).
+  def extract_links(content)
+    LinksSection.extract_section(IntentValidator.body_of(content))
+  rescue LinksSection::AmbiguousLinks
+    "(ambiguous: multiple ## Links headings)"
+  end
+
+  # Always write the audit (even in dry-run, so the human reviews the plan).
+  def emit_audit(store_list, results)
+    text = render_audit(store_list, results)
+    FileUtils.mkdir_p(File.dirname(audit_path))
+    File.write(audit_path, text)
+    text
+  end
+
+  STATUS_ORDER = %i[regenerated added unchanged failed].freeze
+  STATUS_LABELS = {
+    regenerated: "Regenerated (had a ## Links, content changed)",
+    added: "Added (no ## Links section, one inserted)",
+    unchanged: "Unchanged (already canonical)",
+    failed: "FAILED (resolver miss, NOT written)",
+  }.freeze
+
+  def render_audit(store_list, results)
+    lines = []
+    lines << "# Audit: store-wide ## Links projection (intent 72)"
+    lines << ""
+    lines << "Generated: #{Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")}#{dry_run ? " (DRY RUN)" : ""}"
+    lines << ""
+
+    total = STATUS_ORDER.to_h do |st|
+      [st, store_list.sum { |s| results[s[:key]][:counts][st] }]
+    end
+    lines << "Totals across all stores: " \
+             "regenerated #{total[:regenerated]}, added #{total[:added]}, " \
+             "unchanged #{total[:unchanged]}, failed #{total[:failed]}."
+    lines << ""
+
+    store_list.each do |s|
+      key = s[:key]
+      res = results[key]
+      counts = res[:counts]
+      lines << "## #{key}"
+      lines << ""
+      lines << "Regenerated #{counts[:regenerated]}, added #{counts[:added]}, " \
+               "unchanged #{counts[:unchanged]}, failed #{counts[:failed]}."
+      lines << ""
+
+      failed = res[:entries].select { |e| e[:status] == :failed }
+      unless failed.empty?
+        lines << "### FAILED (#{failed.size})"
+        failed.each { |e| lines << "- #{e[:id]}: #{e[:error]}" }
+        lines << ""
+      end
+
+      sample = res[:entries].select { |e| %i[regenerated added].include?(e[:status]) }.first(5)
+      next if sample.empty?
+
+      lines << "### Sample before/after (first #{sample.size})"
+      sample.each do |e|
+        lines << "- #{e[:id]} (#{e[:status]}):"
+        lines << "  - BEFORE:"
+        block_lines(e[:before]).each { |l| lines << "    #{l}" }
+        lines << "  - AFTER:"
+        block_lines(e[:after]).each { |l| lines << "    #{l}" }
+      end
+      lines << ""
+    end
+
+    lines.join("\n") + "\n"
+  end
+
+  def block_lines(text)
+    s = text.to_s.strip
+    return ["(none)"] if s.empty?
+
+    s.lines.map(&:rstrip)
+  end
+
+  # True iff any intent failed (resolver miss).
+  def any_failed?(results)
+    results.values.any? { |r| r[:counts][:failed].to_i.positive? }
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  home = ProjectLinks::DEFAULT_HOME
+  dry = false
+  audit = nil
+  i = 0
+  while i < ARGV.length
+    case ARGV[i]
+    when "--plastic-home" then home = ARGV[i + 1]; i += 2
+    when "--dry-run" then dry = true; i += 1
+    when "--audit-path" then audit = ARGV[i + 1]; i += 2
+    else i += 1
+    end
+  end
+
+  tool = ProjectLinks.new(plastic_home: home, dry_run: dry, audit_path: audit)
+  results = tool.run
+  totals = ProjectLinks::STATUS_ORDER.to_h do |st|
+    [st, results.values.sum { |r| r[:counts][st] }]
+  end
+  puts "project-links #{dry ? "DRY RUN" : "applied"}: " \
+       "regenerated #{totals[:regenerated]}, added #{totals[:added]}, " \
+       "unchanged #{totals[:unchanged]}, failed #{totals[:failed]} " \
+       "across #{results.size} store(s)."
+  puts "Audit: #{tool.audit_path}"
+  exit 1 if tool.any_failed?(results)
+end