@zalom/plastic 1.2.0 → 1.4.0

package/scripts/project-links

@@ -3,13 +3,26 @@
 # 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.
+# canonical I5 `## Links` section, store-wide across every discovered store
+# (intent 72; intent 189 made discovery store-wide). Deterministic: a second
+# run over a projected store changes zero files (idempotent). Touches ONLY the
+# `## Links` section of each intent file; frontmatter and every other section
+# stay byte-identical.
+#
+# PLASTIC.md's `## Links` contract has two halves: never hand-write a line, and
+# NEVER AUTO-DELETE one. Before intent 192 this tool violated the second half:
+# it rebuilt `## Links` purely from frontmatter, silently discarding any
+# existing line with no sources/chain edge behind it, real relationship or
+# not. Now: a line unbacked by frontmatter that still RESOLVES to a real,
+# currently-discovered intent is an ORPHAN CANDIDATE, preserved by default and
+# reported in the audit, never silently deleted. Pass --drop-unbacked-links to
+# delete orphan candidates deliberately (reported separately from a silent
+# drop). A line that resolves to nothing (a broken or mistyped wikilink) is
+# still dropped silently, exactly as before: it names no real relationship to
+# lose.
 #
 # Usage:
-#   project-links [--plastic-home PATH] [--dry-run] [--audit-path PATH]
+#   project-links [--plastic-home PATH] [--dry-run] [--audit-path PATH] [--drop-unbacked-links]
 #
 # 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
@@ -24,6 +37,7 @@ require_relative "lib/intent_validator"
 require_relative "lib/graph_rebuild"
 require_relative "lib/links_projection"
 require_relative "lib/links_section"
+require_relative "lib/store_discovery"
 
 class ProjectLinks
   DEFAULT_HOME = File.join(Dir.home, ".plastic")
@@ -32,9 +46,11 @@ class ProjectLinks
   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)
+  def initialize(plastic_home: DEFAULT_HOME, dry_run: false, audit_path: nil,
+                 drop_unbacked_links: false)
     @plastic_home = plastic_home
     @dry_run = dry_run
+    @drop_unbacked_links = drop_unbacked_links
 
     # 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`
@@ -52,26 +68,23 @@ class ProjectLinks
       end
   end
 
-  attr_reader :plastic_home, :dry_run, :audit_path
+  attr_reader :plastic_home, :dry_run, :audit_path, :drop_unbacked_links
 
-  # The three in-scope stores, each as { key:, root:, store:, index: }.
+  # Every store in scope: global plus every projects/<slug>/store directory that exists
+  # (intent 189). Shares its definition with rebuild-graph, doctor.rb, and new-intent via
+  # StoreDiscovery, so this tool can never again disagree with doctor about what exists.
   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
+    discovery[:stores]
+  end
 
-    %w[plastic knowdb].each do |slug|
-      root = File.join(plastic_home, "projects", slug)
-      store = File.join(root, "store")
-      next unless File.directory?(store)
+  # Registered projects.yml slugs with no store directory on disk (intent 189 D5).
+  # Reported in the audit rather than silently treated as an empty store.
+  def missing_stores
+    discovery[:missing]
+  end
 
-      list << { key: "project:#{slug}", root: root, store: store,
-                index: File.join(root, "INDEX.md") }
-    end
-    list
+  def discovery
+    @discovery ||= StoreDiscovery.discover(plastic_home)
   end
 
   # { id => { sources:, chain:, basename:, label:, path: } } for one store.
@@ -131,7 +144,8 @@ class ProjectLinks
   end
 
   # Project every intent in ONE store. Returns
-  # { entries: [ {id:, status:, before:, after:, error:} ], counts: {...} }.
+  # { entries: [ {id:, status:, before:, after:, error:, orphans_preserved:,
+  #   orphans_dropped_optin:} ], counts: {...} }.
   def project_store(referer_store, nodes, relocation_map:, store_index:, node_index:)
     entries = []
     nodes.each do |id, node|
@@ -143,38 +157,89 @@ class ProjectLinks
       end
 
       content = File.read(node[:path])
+      old_text = extract_links(content) # never raises; ambiguous -> a placeholder string
 
       begin
         had_links = LinksSection.links_heading?(IntentValidator.body_of(content))
-        section_text = LinksProjection.section(
+        canonical_text = LinksProjection.section(
           sources: node[:sources], chain: node[:chain], resolve: resolve
         )
+        kept, dropped_optin = orphan_split(old_text, canonical_text, referer_store,
+                                            store_index, node_index)
+        section_text = LinksProjection.render_entries(
+          LinksProjection.parse_entries(canonical_text) + kept
+        )
         updated = LinksSection.rewrite(content, section_text)
       rescue LinksProjection::UnresolvedRef, LinksSection::AmbiguousLinks => e
-        entries << { id: id, status: :failed, error: e.message }
+        entries << { id: id, status: :failed, error: e.message,
+                     orphans_preserved: [], orphans_dropped_optin: [] }
         next
       end
 
       if updated == content
-        entries << { id: id, status: :unchanged }
+        entries << { id: id, status: :unchanged,
+                     orphans_preserved: kept, orphans_dropped_optin: dropped_optin }
         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 }
+      entries << { id: id, status: status, before: old_text, after: section_text,
+                   orphans_preserved: kept, orphans_dropped_optin: dropped_optin }
     end
 
     counts = entries.each_with_object(Hash.new(0)) { |e, h| h[e[:status]] += 1 }
     { entries: entries, counts: counts }
   end
 
+  # Split the OLD (pre-mutation) `## Links` entries into orphans to KEEP
+  # (unbacked by frontmatter but resolve to a real, currently-discovered
+  # intent) vs DROP under the explicit --drop-unbacked-links opt-in. An entry
+  # that resolves nowhere is neither: it is dropped silently, exactly as before
+  # intent 192 (this is dealintell 3b's three broken single-dash lines:
+  # garbage, not data). Returns [kept_entries, dropped_optin_entries], both
+  # [{target:, label:}].
+  def orphan_split(old_text, canonical_text, referer_store, store_index, node_index)
+    canonical_targets = LinksProjection.parse_entries(canonical_text).map { |e| e[:target] }
+    kept = []
+    dropped_optin = []
+    LinksProjection.parse_entries(old_text).each do |oe|
+      next if canonical_targets.include?(oe[:target]) # already backed; not an orphan
+
+      label = resolve_orphan_label(oe[:target], referer_store, store_index, node_index)
+      next if label.nil? # dead: not backed AND does not resolve; silent drop, as before
+
+      if drop_unbacked_links
+        dropped_optin << oe
+      else
+        kept << { target: oe[:target], label: label }
+      end
+    end
+    [kept, dropped_optin]
+  end
+
+  # Does `target` (already in projected `id--slug` or `store:id--slug` form)
+  # name a real, currently-discovered intent? Returns its CURRENT canonical
+  # label when so (self-healing a stale hand-typed label), else nil (genuinely
+  # dead/broken, e.g. 3b's single-dash mismatches that no real basename
+  # matches).
+  def resolve_orphan_label(target, referer_store, store_index, node_index)
+    if target.include?(":")
+      slug, basename = target.split(":", 2)
+      key = LinksProjection.canonical_store_key(slug, store_index)
+    else
+      key = referer_store
+      basename = target
+    end
+    node = (node_index[key] || {}).values.find { |v| v[:basename] == basename }
+    node && node[:label]
+  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).
+  # content, for the audit sample and for orphan-candidate detection. 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
@@ -207,11 +272,22 @@ class ProjectLinks
     total = STATUS_ORDER.to_h do |st|
       [st, store_list.sum { |s| results[s[:key]][:counts][st] }]
     end
+    total_preserved = store_list.sum { |s| results[s[:key]][:entries].sum { |e| Array(e[:orphans_preserved]).size } }
+    total_dropped_optin = store_list.sum { |s| results[s[:key]][:entries].sum { |e| Array(e[:orphans_dropped_optin]).size } }
     lines << "Totals across all stores: " \
              "regenerated #{total[:regenerated]}, added #{total[:added]}, " \
-             "unchanged #{total[:unchanged]}, failed #{total[:failed]}."
+             "unchanged #{total[:unchanged]}, failed #{total[:failed]}. " \
+             "Unbacked Links lines preserved as orphan candidates: #{total_preserved}" \
+             "#{drop_unbacked_links ? ", dropped via --drop-unbacked-links: #{total_dropped_optin}" : ""}."
     lines << ""
 
+    unless missing_stores.empty?
+      lines << "## Registered projects with no store on disk"
+      lines << ""
+      missing_stores.each { |m| lines << "- #{m[:slug]} (#{m[:project_dir]})" }
+      lines << ""
+    end
+
     store_list.each do |s|
       key = s[:key]
       res = results[key]
@@ -229,6 +305,22 @@ class ProjectLinks
         lines << ""
       end
 
+      preserved = res[:entries].flat_map { |e| Array(e[:orphans_preserved]).map { |o| [e[:id], o] } }
+      unless preserved.empty?
+        lines << "### Orphan candidates preserved (#{preserved.size})"
+        lines << "Unbacked by sources/chain but resolve to a real intent; add the frontmatter " \
+                 "edge if the relationship is real, or re-run with --drop-unbacked-links if not."
+        preserved.each { |id, o| lines << "- #{id}: -> #{o[:target]}" }
+        lines << ""
+      end
+
+      dropped_optin = res[:entries].flat_map { |e| Array(e[:orphans_dropped_optin]).map { |o| [e[:id], o] } }
+      unless dropped_optin.empty?
+        lines << "### Orphan candidates DROPPED (--drop-unbacked-links) (#{dropped_optin.size})"
+        dropped_optin.each { |id, o| lines << "- #{id}: -> #{o[:target]}" }
+        lines << ""
+      end
+
       sample = res[:entries].select { |e| %i[regenerated added].include?(e[:status]) }.first(5)
       next if sample.empty?
 
@@ -263,17 +355,22 @@ if $PROGRAM_NAME == __FILE__
   home = ProjectLinks::DEFAULT_HOME
   dry = false
   audit = nil
+  drop = false
   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
+    when "--drop-unbacked-links" then drop = true; i += 1
+    else
+      abort "project-links: unknown argument #{ARGV[i].inspect} " \
+            "(usage: --plastic-home PATH | --dry-run | --audit-path PATH | --drop-unbacked-links)"
     end
   end
 
-  tool = ProjectLinks.new(plastic_home: home, dry_run: dry, audit_path: audit)
+  tool = ProjectLinks.new(plastic_home: home, dry_run: dry, audit_path: audit,
+                           drop_unbacked_links: drop)
   results = tool.run
   totals = ProjectLinks::STATUS_ORDER.to_h do |st|
     [st, results.values.sum { |r| r[:counts][st] }]

package/scripts/provision-project-store

@@ -12,10 +12,12 @@
 # nothing.
 #
 # Usage:
-#   provision-project-store <slug> [--home <path>]
+#   provision-project-store <slug> [--home <path>] [--package-root <path>]
 #
 # Exit codes: 0 (store provisioned), 1 (unregistered slug / error on stderr),
 # 2 (usage). --home <path> overrides the Plastic home (default: ~/.plastic).
+# --package-root <path> overrides where templates/ resolves from (default:
+# StoreProvisioning::PACKAGE_ROOT, the repo root); mainly for hermetic tests.
 
 require_relative "lib/store_provisioning"
 
@@ -27,22 +29,33 @@ def plastic_home(args)
   end
 end
 
+def package_root(args)
+  if (i = args.index("--package-root")) && args[i + 1]
+    File.expand_path(args[i + 1])
+  else
+    StoreProvisioning::PACKAGE_ROOT
+  end
+end
+
 home = plastic_home(ARGV)
+root = package_root(ARGV)
 
-# First positional arg, skipping any flag and the value that follows --home.
+# First positional arg, skipping any flag and the value that follows --home
+# or --package-root.
 home_value_index = (i = ARGV.index("--home")) ? i + 1 : nil
+package_root_value_index = (i = ARGV.index("--package-root")) ? i + 1 : nil
 slug_index = ARGV.each_index.find do |idx|
   arg = ARGV[idx]
-  !arg.start_with?("--") && idx != home_value_index
+  !arg.start_with?("--") && idx != home_value_index && idx != package_root_value_index
 end
 slug = slug_index && ARGV[slug_index]
 
 if slug.nil?
-  warn "usage: provision-project-store <slug> [--home <path>]"
+  warn "usage: provision-project-store <slug> [--home <path>] [--package-root <path>]"
   exit 2
 end
 
-result = StoreProvisioning.provision(slug, plastic_home: home)
+result = StoreProvisioning.provision(slug, plastic_home: home, package_root: root)
 
 if result[:ok]
   puts "OK: #{result[:store_dir]}"

package/scripts/read-config

@@ -20,6 +20,7 @@ DEFAULTS = {
   "max_slug_words" => 5,
   "project_roots" => ["~/.plastic/projects"],
   "deprecations_dismissed" => [],
+  "config_asks_dismissed" => [],
   "agent" => {
     "type" => "claude-code",
     "parallel_mode" => "linear"

package/scripts/rebuild-graph

@@ -24,6 +24,7 @@ require "fileutils"
 require_relative "lib/graph_rebuild"
 require_relative "lib/frontmatter_writer"
 require_relative "lib/intent_validator"
+require_relative "lib/store_discovery"
 
 class RebuildGraph
   DEFAULT_HOME = File.join(Dir.home, ".plastic")
@@ -65,23 +66,24 @@ class RebuildGraph
 
   attr_reader :plastic_home, :dry_run, :audit_path
 
-  # The three in-scope stores, each as { key:, root:, store:, index: }.
-  # `root` is the dir holding INDEX.md; `store` is the intents dir.
+  # Every store in scope: global plus every projects/<slug>/store directory that exists
+  # (intent 189). A superset of reality, not a hardcoded list: missing a real store here
+  # means a live cross-store ref into it gets classified :dead and DELETED (the exact bug
+  # this discovery fixes); including one nobody registered is harmless. Single source of
+  # truth is StoreDiscovery, shared with project-links, doctor.rb, and new-intent.
   def stores
-    list = []
-    global_store = File.join(plastic_home, "store")
-    list << { key: "global", root: plastic_home, store: global_store,
-              index: File.join(plastic_home, "INDEX.md") } if File.directory?(global_store)
-
-    %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
+    discovery[:stores]
+  end
+
+  # Registered projects.yml slugs with no store directory on disk (legal;
+  # plastic-store-provisioning exists for exactly this state). Reported in the audit
+  # (intent 189 D5) so this never looks like a silent empty store.
+  def missing_stores
+    discovery[:missing]
+  end
+
+  def discovery
+    @discovery ||= StoreDiscovery.discover(plastic_home)
   end
 
   # { id => { sources:, chain:, path: } } for one store.
@@ -169,14 +171,33 @@ class RebuildGraph
   # PURE-ish formatter (string from results). Per-store, grouped by kind.
   def render_audit(store_list, results)
     total = store_list.sum { |s| results[s[:key]][:changes].size }
+    preserved_unknown = store_list.flat_map { |s| results[s[:key]][:preserved] }
     lines = []
     lines << "# Audit: store-wide sources/chain graph rebuild (intent 49)"
     lines << ""
     lines << "Generated: #{Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")}#{dry_run ? " (DRY RUN)" : ""}"
     lines << ""
     lines << "Total changes across all stores: #{total}"
+    lines << "Unknown-store refs preserved (NOT dropped): #{preserved_unknown.size}"
     lines << ""
 
+    unless preserved_unknown.empty?
+      lines << "## Unknown-store refs preserved (store not recognized this run; check " \
+               "projects.yml and store discovery before trusting a zero-change result)"
+      lines << ""
+      preserved_unknown.each do |p|
+        lines << "- #{p[:intent]}.#{p[:field]}: #{p[:ref]} (store #{p[:store].inspect} not recognized)"
+      end
+      lines << ""
+    end
+
+    unless missing_stores.empty?
+      lines << "## Registered projects with no store on disk"
+      lines << ""
+      missing_stores.each { |m| lines << "- #{m[:slug]} (#{m[:project_dir]})" }
+      lines << ""
+    end
+
     store_list.each do |s|
       key = s[:key]
       changes = results[key][:changes]
@@ -232,13 +253,17 @@ if $PROGRAM_NAME == __FILE__
     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
+    else
+      abort "rebuild-graph: unknown argument #{ARGV[i].inspect} " \
+            "(usage: --plastic-home PATH | --dry-run | --audit-path PATH)"
     end
   end
 
   tool = RebuildGraph.new(plastic_home: home, dry_run: dry, audit_path: audit)
   results = tool.run
   total = results.values.sum { |r| r[:changes].size }
+  preserved = results.values.sum { |r| r[:preserved].size }
   puts "rebuild-graph #{dry ? "DRY RUN" : "applied"}: #{total} change(s) across #{results.size} store(s)."
+  puts "Unknown-store refs preserved (not dropped): #{preserved}" if preserved.positive?
   puts "Audit: #{tool.audit_path}"
 end