@zalom/plastic 1.4.1 → 1.6.0

package/scripts/maintenance-run

@@ -0,0 +1,236 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# maintenance-run - the maintenance dispatch wrapper (intent 197). DETECTS (never acquires) a
+# target intent's delivery lock (Lock.fresh?) and defers if fresh; otherwise runs the
+# requested tool inside MaintenanceGit.run_scoped so the change and its revisions.md receipt
+# land as ONE scoped, merged commit on the store's own main, never via `git add -A`.
+#
+# Dry-run by DEFAULT (mirrors restore-intent-v1's higher-blast-radius default, since this
+# tool commits and merges on the shared store repo); --apply is required to write anything.
+#
+# Usage:
+#   maintenance-run --tool project-links --intent <id> [--store <key>] [--plastic-home PATH] [--apply]
+#   maintenance-run --tool rebuild-graph [--plastic-home PATH] [--apply]
+#   maintenance-run --tool restore-intent-v1 <id> --at <ref> [--plastic-home PATH] [--apply] [--skip-links]
+#
+# project-links here is ALWAYS single-intent: --intent is required. A store-wide
+# project-links sweep is the rare, owner-approved batch exception (D2) and is run directly
+# with the plain `project-links` tool, never through this wrapper.
+#
+# --store <key> (a StoreDiscovery key, e.g. "global" or "project:dealintell") disambiguates
+# a bare id that exists in more than one store (real, live examples: ids 26 and 15 both
+# collide across stores today) - both project-links --intent and restore-intent-v1's own id
+# resolution abort loud naming every candidate when ambiguous and --store is not given;
+# never silently pick the first match.
+#
+# Exit codes: 0 applied or clean no-op; 1 usage error; 2 deferred (a target holds a fresh
+# delivery lock); 3 the underlying tool reported failure; 4 precondition failed (the store
+# working tree was not clean, or is not a git repo at all).
+
+require "open3"
+require "time"
+
+require_relative "lib/store_discovery"
+require_relative "lib/lock"
+require_relative "lib/maintenance_git"
+
+DEFAULT_HOME = File.join(Dir.home, ".plastic")
+
+# Resolves `id` to exactly one directory. `store:` (a StoreDiscovery key) short-circuits
+# resolution to that one store. Without it, more than one matching store is an ambiguity
+# this method itself aborts on (never silently pick the first match - the same class of bug
+# ACTION_1 fixes inside project-links itself; this helper guards every OTHER caller of
+# resolve_dir_for_id, i.e. rebuild-graph's touched-id lock scan and restore-intent-v1's id
+# resolution, both of which route through this one function).
+def resolve_dir_for_id(discovery, id, store: nil)
+  matches = []
+  discovery[:stores].each do |s|
+    next if store && s[:key] != store
+
+    Dir.children(s[:store]).reject { |e| e.start_with?(".") }.each do |entry|
+      full = File.join(s[:store], entry)
+      next unless File.directory?(full)
+
+      matches << [s[:key], full] if entry.split("--", 2).first == id.to_s
+    end
+  end
+
+  return nil if matches.empty?
+  if matches.length > 1
+    abort_loud("intent #{id.inspect} is ambiguous across stores " \
+               "(#{matches.map(&:first).join(", ")}); pass --store <key> to disambiguate")
+  end
+  matches.first.last
+end
+
+def abort_loud(msg, code = 1)
+  warn "maintenance-run: #{msg}"
+  exit code
+end
+
+def parse_argv(argv)
+  opts = { tool: nil, intent: nil, store: nil, plastic_home: DEFAULT_HOME, apply: false,
+           at: nil, skip_links: false, id: nil }
+  i = 0
+  while i < argv.length
+    case argv[i]
+    when "--tool" then opts[:tool] = argv[i += 1]
+    when "--intent" then opts[:intent] = argv[i += 1]
+    when "--store" then opts[:store] = argv[i += 1]
+    when "--plastic-home" then opts[:plastic_home] = argv[i += 1]
+    when "--apply" then opts[:apply] = true
+    when "--at" then opts[:at] = argv[i += 1]
+    when "--skip-links" then opts[:skip_links] = true
+    else
+      opts[:id] ||= argv[i] # positional id, restore-intent-v1 only
+    end
+    i += 1
+  end
+  opts
+end
+
+def check_not_fresh!(dir, id)
+  return unless dir && Lock.fresh?(dir)
+
+  abort_loud("deferred: intent #{id} holds a FRESH delivery lock; an active delivery is in " \
+             "progress. Maintenance never acquires a lock and never waits on one; re-run " \
+             "once the delivery finishes or the lock goes stale.", 2)
+end
+
+def stamp
+  Time.now.utc.strftime("%Y%m%d%H%M%S")
+end
+
+def report_result(result)
+  if result[:committed]
+    puts "maintenance-run: applied and merged (#{result[:changed].size} path(s)): " \
+         "#{result[:changed].join(", ")}"
+  else
+    puts "maintenance-run: no change (already canonical)."
+  end
+  exit 0
+end
+
+def run_project_links(home, intent, store, apply)
+  abort_loud("--tool project-links requires --intent <id> (a store-wide sweep runs " \
+             "scripts/project-links directly, never through maintenance-run)") unless intent
+
+  discovery = StoreDiscovery.discover(home)
+  dir = resolve_dir_for_id(discovery, intent, store: store) # aborts loud itself on ambiguity
+  abort_loud("intent #{intent} not found under #{home}#{store ? " (--store #{store})" : ""}") unless dir
+  check_not_fresh!(dir, intent)
+
+  tool_path = File.expand_path("project-links", __dir__)
+  base_args = ["--plastic-home", home, "--intent", intent]
+  base_args += ["--store", store] if store
+
+  unless apply
+    system(RbConfig.ruby, tool_path, *base_args, "--dry-run")
+    exit($?.exitstatus)
+  end
+
+  begin
+    result = MaintenanceGit.run_scoped(
+      repo_dir: home, branch_name: "maintenance/project-links-#{intent}-#{stamp}",
+      commit_message: "chore: maintenance - project-links --intent #{intent}"
+    ) do
+      ok = system(RbConfig.ruby, tool_path, *base_args)
+      raise "project-links failed for #{intent}" unless ok
+    end
+  rescue MaintenanceGit::DirtyWorkingTree, MaintenanceGit::NotAGitRepo => e
+    abort_loud(e.message, 4)
+  rescue RuntimeError => e
+    abort_loud(e.message, 3)
+  end
+  report_result(result)
+end
+
+def run_rebuild_graph(home, apply)
+  tool_path = File.expand_path("rebuild-graph", __dir__)
+  load tool_path unless defined?(RebuildGraph) # matches test/*_test.rb's own load convention
+
+  discovery = StoreDiscovery.discover(home)
+  dry = RebuildGraph.new(plastic_home: home, dry_run: true)
+  dry_results = dry.run
+  touched_ids = dry_results.values.flat_map { |r| r[:changes].map { |c| c[:intent] } }.uniq
+
+  touched_ids.each { |id| check_not_fresh!(resolve_dir_for_id(discovery, id), id) }
+
+  unless apply
+    puts "maintenance-run: DRY RUN, #{touched_ids.size} intent(s) would change: #{touched_ids.join(", ")}"
+    exit 0
+  end
+
+  begin
+    result = MaintenanceGit.run_scoped(
+      repo_dir: home, branch_name: "maintenance/rebuild-graph-#{stamp}",
+      commit_message: "chore: maintenance - rebuild-graph"
+    ) do
+      ok = system(RbConfig.ruby, tool_path, "--plastic-home", home)
+      raise "rebuild-graph failed" unless ok
+    end
+  rescue MaintenanceGit::DirtyWorkingTree, MaintenanceGit::NotAGitRepo => e
+    abort_loud(e.message, 4)
+  rescue RuntimeError => e
+    abort_loud(e.message, 3)
+  end
+  report_result(result)
+end
+
+def run_restore_intent_v1(home, id, at, store, apply, skip_links)
+  abort_loud("restore-intent-v1 requires an intent id and --at <ref>") unless id && at
+
+  discovery = StoreDiscovery.discover(home)
+  # NOTE: restore-intent-v1's own CLI (scripts/restore-intent-v1:219-238, find_intent_dir)
+  # already aborts loud on a cross-store id collision; this resolve_dir_for_id call is only
+  # for the LOCK CHECK here (maintenance-run must know which one directory to check
+  # Lock.fresh? against). --store is honored the same way for consistency; if omitted and
+  # the id is ambiguous, this call aborts BEFORE restore-intent-v1 itself would have run.
+  dir = resolve_dir_for_id(discovery, id, store: store)
+  abort_loud("intent #{id} not found under #{home}#{store ? " (--store #{store})" : ""}") unless dir
+  check_not_fresh!(dir, id)
+
+  tool_path = File.expand_path("restore-intent-v1", __dir__)
+  args = [tool_path, id, "--at", at, "--plastic-home", home]
+  args << "--skip-links" if skip_links
+
+  unless apply
+    system(RbConfig.ruby, *args)
+    exit($?.exitstatus)
+  end
+
+  begin
+    result = MaintenanceGit.run_scoped(
+      repo_dir: home, branch_name: "maintenance/restore-intent-v1-#{id}-#{stamp}",
+      commit_message: "chore: maintenance - restore-intent-v1 #{id}"
+    ) do
+      ok = system(RbConfig.ruby, *args, "--apply")
+      raise "restore-intent-v1 failed for #{id}" unless ok
+    end
+  rescue MaintenanceGit::DirtyWorkingTree, MaintenanceGit::NotAGitRepo => e
+    abort_loud(e.message, 4)
+  rescue RuntimeError => e
+    abort_loud(e.message, 3)
+  end
+  report_result(result)
+end
+
+def main(argv)
+  opts = parse_argv(argv)
+  abort_loud("--tool is required (project-links|rebuild-graph|restore-intent-v1)") unless opts[:tool]
+
+  case opts[:tool]
+  when "project-links"
+    run_project_links(opts[:plastic_home], opts[:intent], opts[:store], opts[:apply])
+  when "rebuild-graph" then run_rebuild_graph(opts[:plastic_home], opts[:apply])
+  when "restore-intent-v1"
+    run_restore_intent_v1(opts[:plastic_home], opts[:id], opts[:at], opts[:store], opts[:apply], opts[:skip_links])
+  else
+    abort_loud("unknown --tool #{opts[:tool].inspect} " \
+               "(expected project-links|rebuild-graph|restore-intent-v1)")
+  end
+end
+
+main(ARGV) if $PROGRAM_NAME == __FILE__

package/scripts/project-links

@@ -18,11 +18,16 @@
 # 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.
+# still dropped from the file (it names no real relationship to keep), but
+# reported in the audit as a malformed-reference finding rather than
+# vanishing without a trace (intent 197).
 #
 # Usage:
 #   project-links [--plastic-home PATH] [--dry-run] [--audit-path PATH] [--drop-unbacked-links]
+#                 [--intent <id> [--store <key>]]
+#
+# --store only matters when --intent alone is ambiguous across stores (the tool
+# aborts loud, naming every candidate store, rather than silently picking one).
 #
 # 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
@@ -38,6 +43,7 @@ require_relative "lib/graph_rebuild"
 require_relative "lib/links_projection"
 require_relative "lib/links_section"
 require_relative "lib/store_discovery"
+require_relative "lib/revisions_writer"
 
 class ProjectLinks
   DEFAULT_HOME = File.join(Dir.home, ".plastic")
@@ -47,10 +53,12 @@ class ProjectLinks
     "projects/plastic/store/72--links-graph-projection/resources/audit--links-projection.md"
 
   def initialize(plastic_home: DEFAULT_HOME, dry_run: false, audit_path: nil,
-                 drop_unbacked_links: false)
+                 drop_unbacked_links: false, intent: nil, store: nil)
     @plastic_home = plastic_home
     @dry_run = dry_run
     @drop_unbacked_links = drop_unbacked_links
+    @intent = intent && intent.to_s
+    @store = store
 
     # 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`
@@ -68,7 +76,7 @@ class ProjectLinks
       end
   end
 
-  attr_reader :plastic_home, :dry_run, :audit_path, :drop_unbacked_links
+  attr_reader :plastic_home, :dry_run, :audit_path, :drop_unbacked_links, :intent, :store
 
   # 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
@@ -130,13 +138,23 @@ class ProjectLinks
 
     relocation_map = GraphRebuild.build_relocation_map(index_texts)
 
+    target_store_key = intent ? resolve_target_store(store_list, nodes_by_store, intent) : nil
+
     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
-      )
+      if intent
+        results[key] = (key == target_store_key) ? project_store(
+          key, nodes_by_store[key],
+          relocation_map: relocation_map, store_index: store_index, node_index: node_index,
+          only: intent
+        ) : { entries: [], counts: Hash.new(0) }
+      else
+        results[key] = project_store(
+          key, nodes_by_store[key],
+          relocation_map: relocation_map, store_index: store_index, node_index: node_index
+        )
+      end
     end
 
     emit_audit(store_list, results)
@@ -146,9 +164,10 @@ class ProjectLinks
   # Project every intent in ONE store. Returns
   # { entries: [ {id:, status:, before:, after:, error:, orphans_preserved:,
   #   orphans_dropped_optin:} ], counts: {...} }.
-  def project_store(referer_store, nodes, relocation_map:, store_index:, node_index:)
+  def project_store(referer_store, nodes, relocation_map:, store_index:, node_index:, only: nil)
     entries = []
     nodes.each do |id, node|
+      next if only && id != only
       resolve = ->(ref) do
         LinksProjection.resolve_ref_projection(
           ref, referer_store: referer_store,
@@ -164,7 +183,7 @@ class ProjectLinks
         canonical_text = LinksProjection.section(
           sources: node[:sources], chain: node[:chain], resolve: resolve
         )
-        kept, dropped_optin = orphan_split(old_text, canonical_text, referer_store,
+        kept, dropped_optin, dead = orphan_split(old_text, canonical_text, referer_store,
                                             store_index, node_index)
         section_text = LinksProjection.render_entries(
           LinksProjection.parse_entries(canonical_text) + kept
@@ -172,42 +191,107 @@ class ProjectLinks
         updated = LinksSection.rewrite(content, section_text)
       rescue LinksProjection::UnresolvedRef, LinksSection::AmbiguousLinks => e
         entries << { id: id, status: :failed, error: e.message,
-                     orphans_preserved: [], orphans_dropped_optin: [] }
+                     orphans_preserved: [], orphans_dropped_optin: [], orphans_dead: [] }
         next
       end
 
       if updated == content
-        entries << { id: id, status: :unchanged,
-                     orphans_preserved: kept, orphans_dropped_optin: dropped_optin }
+        entries << { id: id, status: :unchanged, orphans_preserved: kept,
+                     orphans_dropped_optin: dropped_optin, orphans_dead: dead }
         next
       end
 
       status = had_links ? :regenerated : :added
-      File.write(node[:path], updated) unless dry_run
+
+      unless dry_run
+        begin
+          RevisionsWriter.append!(
+            File.dirname(node[:path]),
+            why: revision_why(status, kept, dropped_optin, dead),
+            rule: "links-projection",
+            prior_location: "#{node[:basename]}.md ## Links",
+            change: revision_change(old_text, section_text)
+          )
+        rescue RevisionsWriter::WriteFailed => e
+          entries << { id: id, status: :failed, error: e.message,
+                       orphans_preserved: [], orphans_dropped_optin: [], orphans_dead: [] }
+          next
+        end
+        File.write(node[:path], updated)
+      end
+
       entries << { id: id, status: status, before: old_text, after: section_text,
-                   orphans_preserved: kept, orphans_dropped_optin: dropped_optin }
+                   orphans_preserved: kept, orphans_dropped_optin: dropped_optin, orphans_dead: dead }
     end
 
     counts = entries.each_with_object(Hash.new(0)) { |e, h| h[e[:status]] += 1 }
     { entries: entries, counts: counts }
   end
 
+  # Resolves --intent to exactly ONE store key, aborting loud on ambiguity (mirrors
+  # scripts/restore-intent-v1's find_intent_dir, which solves this identical cross-store
+  # id-collision problem the same way). `store:` (explicit --store) short-circuits resolution
+  # when the caller already knows which store; otherwise every store containing a matching
+  # id is a candidate, and more than one is a hard abort (never silently pick one). An id
+  # found in NO store is not an error (unlike restore-intent-v1's higher blast radius): it
+  # resolves to nil, so every store gets the synthetic zero-activity result in `run` (a
+  # provably observable no-op, not a crash) rather than aborting a caller that may be
+  # running this defensively (e.g. before an id is known to exist yet).
+  def resolve_target_store(store_list, nodes_by_store, intent)
+    if store
+      abort "project-links: --store #{store.inspect} has no intent #{intent.inspect}" \
+        unless nodes_by_store[store]&.key?(intent)
+      return store
+    end
+
+    candidates = store_list.select { |s| nodes_by_store[s[:key]].key?(intent) }.map { |s| s[:key] }
+    return nil if candidates.empty?
+    if candidates.length > 1
+      abort "project-links: intent #{intent.inspect} is ambiguous across stores " \
+            "(#{candidates.join(", ")}); pass --store <key> to disambiguate (e.g. --store " \
+            "#{candidates.first})"
+    end
+    candidates.first
+  end
+
+  # Renders the one-sentence "Why" for a project-links-authored receipt. Free text; the
+  # [rule: tag] suffix is appended by RevisionsWriter itself, not here.
+  def revision_why(status, kept, dropped_optin, dead)
+    parts = []
+    parts << (status == :added ? "added a missing ## Links section" : "regenerated ## Links to match frontmatter")
+    parts << "dropped #{dead.size} unresolvable reference(s)" unless dead.empty?
+    parts << "dropped #{dropped_optin.size} unbacked-but-resolvable reference(s) (--drop-unbacked-links)" unless dropped_optin.empty?
+    parts.join("; ")
+  end
+
+  def revision_change(before_text, after_text)
+    "## Links regenerated (before -> after)\n\n  BEFORE:\n" \
+      "#{block_lines(before_text).map { |l| "    #{l}" }.join("\n")}\n\n  AFTER:\n" \
+      "#{block_lines(after_text).map { |l| "    #{l}" }.join("\n")}"
+  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:}].
+  # that resolves nowhere is neither: it is dropped from the file (nothing real to
+  # preserve) but reported as a malformed-reference finding, not silently (intent 197;
+  # this is dealintell 3b's three broken single-dash lines: garbage, not data).
+  # Returns [kept_entries, dropped_optin_entries, dead_entries].
   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 = []
+    dead = []
     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 label.nil?
+        # Resolves to nothing: still dropped from the file (nothing real to preserve),
+        # but no longer silent. Reported as a malformed-orphan candidate in the audit.
+        dead << { target: oe[:target] }
+        next
+      end
 
       if drop_unbacked_links
         dropped_optin << oe
@@ -215,7 +299,7 @@ class ProjectLinks
         kept << { target: oe[:target], label: label }
       end
     end
-    [kept, dropped_optin]
+    [kept, dropped_optin, dead]
   end
 
   # Does `target` (already in projected `id--slug` or `store:id--slug` form)
@@ -267,6 +351,7 @@ class ProjectLinks
     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 << "Scoped to intent #{intent} only (--intent)." if intent
     lines << ""
 
     total = STATUS_ORDER.to_h do |st|
@@ -274,11 +359,13 @@ class ProjectLinks
     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 } }
+    total_dead = store_list.sum { |s| results[s[:key]][:entries].sum { |e| Array(e[:orphans_dead]).size } }
     lines << "Totals across all stores: " \
              "regenerated #{total[:regenerated]}, added #{total[:added]}, " \
              "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}" : ""}."
+             "#{drop_unbacked_links ? ", dropped via --drop-unbacked-links: #{total_dropped_optin}" : ""}" \
+             ", malformed references found: #{total_dead}."
     lines << ""
 
     unless missing_stores.empty?
@@ -321,6 +408,17 @@ class ProjectLinks
         lines << ""
       end
 
+      dead_refs = res[:entries].flat_map { |e| Array(e[:orphans_dead]).map { |o| [e[:id], o] } }
+      unless dead_refs.empty?
+        lines << "### Malformed references found, dropped silently before this fix (#{dead_refs.size})"
+        lines << "Resolve to no real intent under any known store; these are dropped from the " \
+                 "regenerated ## Links section (nothing real to preserve), but were previously " \
+                 "invisible to every check. Confirm each is genuinely dead (a typo'd slug, a " \
+                 "sibling wrongly linked) rather than a missing store/relocation before trusting."
+        dead_refs.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?
 
@@ -356,6 +454,8 @@ if $PROGRAM_NAME == __FILE__
   dry = false
   audit = nil
   drop = false
+  intent = nil
+  store = nil
   i = 0
   while i < ARGV.length
     case ARGV[i]
@@ -363,14 +463,17 @@ if $PROGRAM_NAME == __FILE__
     when "--dry-run" then dry = true; i += 1
     when "--audit-path" then audit = ARGV[i + 1]; i += 2
     when "--drop-unbacked-links" then drop = true; i += 1
+    when "--intent" then intent = ARGV[i + 1]; i += 2
+    when "--store" then store = ARGV[i + 1]; i += 2
     else
       abort "project-links: unknown argument #{ARGV[i].inspect} " \
-            "(usage: --plastic-home PATH | --dry-run | --audit-path PATH | --drop-unbacked-links)"
+            "(usage: --plastic-home PATH | --dry-run | --audit-path PATH | " \
+            "--drop-unbacked-links | --intent <id> [--store <key>])"
     end
   end
 
   tool = ProjectLinks.new(plastic_home: home, dry_run: dry, audit_path: audit,
-                           drop_unbacked_links: drop)
+                           drop_unbacked_links: drop, intent: intent, store: store)
   results = tool.run
   totals = ProjectLinks::STATUS_ORDER.to_h do |st|
     [st, results.values.sum { |r| r[:counts][st] }]

package/scripts/rebuild-graph

@@ -25,6 +25,7 @@ require_relative "lib/graph_rebuild"
 require_relative "lib/frontmatter_writer"
 require_relative "lib/intent_validator"
 require_relative "lib/store_discovery"
+require_relative "lib/revisions_writer"
 
 class RebuildGraph
   DEFAULT_HOME = File.join(Dir.home, ".plastic")
@@ -47,6 +48,7 @@ class RebuildGraph
   def initialize(plastic_home: DEFAULT_HOME, dry_run: false, audit_path: nil)
     @plastic_home = plastic_home
     @dry_run = dry_run
+    @write_failures = []
 
     # A dry run must NOT stomp the canonical audit (the spec/checklist tell humans
     # to run --dry-run to review the plan). When no explicit --audit-path is given,
@@ -64,7 +66,11 @@ class RebuildGraph
       end
   end
 
-  attr_reader :plastic_home, :dry_run, :audit_path
+  attr_reader :plastic_home, :dry_run, :audit_path, :write_failures
+
+  def any_write_failures?
+    !write_failures.empty?
+  end
 
   # 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
@@ -140,11 +146,15 @@ class RebuildGraph
     results
   end
 
-  # Write changed frontmatter back via the minimal style-preserving writer.
+  # Write changed frontmatter back via the minimal style-preserving writer. Every applied
+  # change writes a revisions.md receipt FIRST (intent 197): if the receipt cannot be
+  # written, the frontmatter change is withheld (reported in write_failures) rather than
+  # left unrecorded.
   def write_back(store_list, nodes_by_store, results)
     store_list.each do |s|
       key = s[:key]
       new_nodes = results[key][:nodes]
+      changes_by_id = results[key][:changes].group_by { |c| c[:intent] }
       nodes_by_store[key].each do |id, original|
         rebuilt = new_nodes[id]
         next if rebuilt.nil?
@@ -154,7 +164,22 @@ class RebuildGraph
         updated = FrontmatterWriter.rewrite_arrays(content,
                                                    sources: rebuilt[:sources],
                                                    chain: rebuilt[:chain])
-        File.write(original[:path], updated) if updated != content
+        next if updated == content
+
+        id_changes = changes_by_id[id] || []
+        begin
+          RevisionsWriter.append!(
+            File.dirname(original[:path]),
+            why: "graph rebuild: #{id_changes.map { |c| c[:kind] }.uniq.join(", ")}",
+            rule: "graph-rebuild",
+            prior_location: "#{File.basename(original[:path], ".md")}.md frontmatter - sources/chain",
+            change: id_changes.map { |c| format_change(c) }.join("; ")
+          )
+        rescue RevisionsWriter::WriteFailed => e
+          @write_failures << { id: id, error: e.message }
+          next
+        end
+        File.write(original[:path], updated)
       end
     end
   end
@@ -191,6 +216,13 @@ class RebuildGraph
       lines << ""
     end
 
+    unless write_failures.empty?
+      lines << "## Frontmatter changes that could NOT be written (revisions.md receipt failed)"
+      lines << ""
+      write_failures.each { |f| lines << "- #{f[:id]}: #{f[:error]}" }
+      lines << ""
+    end
+
     unless missing_stores.empty?
       lines << "## Registered projects with no store on disk"
       lines << ""
@@ -266,4 +298,6 @@ if $PROGRAM_NAME == __FILE__
   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}"
+  puts "Write failures (receipt could not be recorded, change withheld): #{tool.write_failures.size}" if tool.any_write_failures?
+  exit 1 if tool.any_write_failures?
 end