@zalom/plastic 1.4.0 → 1.5.0

package/scripts/plastic-lock

@@ -5,10 +5,11 @@
 # plastic-lock: inspect and repair the durable delivery lock (intent 108, D5),
 # and take/free per-artifact claim tokens (intent 111 D1/D5).
 #
-# Usage: plastic-lock <status|fix|release|reclaim|delegate|claim|release-claim>
+# Usage: plastic-lock <status|who|fix|release|reclaim|delegate|claim|release-claim>
 #          [--intent-dir DIR] [--session SID] [--delegate SID] [--artifact NAME]
 #
 # Verbs:
+#   who           compact, read-only durable owner/activity view
 #   status        report the lock file, the bridge cache, their agreement,
 #                 and any live per-artifact claims
 #   fix           idempotent repair: rebuild lock + bridge from disk truth for
@@ -29,13 +30,15 @@ require_relative "lib/bridge"
 require_relative "lib/lock"
 
 def usage!
-  warn "usage: plastic-lock <status|fix|release|reclaim|delegate|claim|release-claim> " \
-       "[--intent-dir DIR] [--session SID] [--delegate SID] [--artifact NAME]"
+  warn "usage: plastic-lock <status|who|fix|release|reclaim|delegate|claim|release-claim> " \
+       "[--intent-dir DIR] [--session SID] [--delegate SID] [--artifact NAME] " \
+       "[--harness claude|codex] [--agent NAME] [--model MODEL] [--thread ID] " \
+       "[--mode auto|guided] [--status finished|failed]"
   exit 1
 end
 
 verb = ARGV.shift
-usage! unless %w[status fix release reclaim delegate claim release-claim].include?(verb)
+usage! unless %w[status who fix release reclaim delegate claim release-claim].include?(verb)
 
 opts = {}
 until ARGV.empty?
@@ -44,17 +47,30 @@ until ARGV.empty?
   when "--session" then opts[:session] = ARGV.shift
   when "--delegate" then opts[:delegate] = ARGV.shift
   when "--artifact" then opts[:artifact] = ARGV.shift
+  when "--harness" then opts[:harness] = ARGV.shift
+  when "--agent" then opts[:agent] = ARGV.shift
+  when "--model" then opts[:model] = ARGV.shift
+  when "--thread" then opts[:thread] = ARGV.shift
+  when "--mode" then opts[:mode] = ARGV.shift
+  when "--status" then opts[:status] = ARGV.shift
   else
     warn "unknown flag #{flag}"
     usage!
   end
 end
+usage! if opts[:mode] && !%w[auto guided].include?(opts[:mode])
 
 session = opts[:session]
 session = ENV["CLAUDE_CODE_SESSION_ID"] if session.nil? || session.strip.empty?
+harness = opts[:harness]
+hint_harness = harness || "claude"
 
 dir = opts[:dir]
 if dir.nil? || dir.strip.empty?
+  if verb == "who"
+    warn "plastic-lock: who is strictly durable-state only; pass --intent-dir <intent dir>"
+    exit 1
+  end
   bridge = Bridge.discover_bridge(session: session, cwd: Dir.pwd)
   dir = Bridge.bridge_intent_dir(bridge)
 end
@@ -64,6 +80,37 @@ if dir.nil?
 end
 dir = File.expand_path(dir)
 
+if verb == "who"
+  view = Lock.who(dir)
+  basename = File.basename(dir)
+  intent_id, slug = basename.split("--", 2)
+  display = ->(value) { value.nil? || value.to_s.strip.empty? || value == "unknown" ? "Unknown" : value.to_s }
+  harness = ->(value) {
+    shown = display.call(value)
+    shown == "Unknown" ? shown : shown.sub(/\A./) { |char| char.upcase }
+  }
+  owner = view["owner"] || {}
+  claims = Array(view["claims"]).select { |claim| claim["fresh"] && !claim["corrupt"] }
+  claim_text = claims.map do |claim|
+    writer = claim["delegate"] || claim["owner_session"]
+    "#{display.call(claim['artifact'])} by #{display.call(writer)}"
+  end
+  delegate = Array(view["delegates"]).last
+
+  puts "#{intent_id} · #{slug || basename}"
+  puts "State: #{view['state']}"
+  puts "Controller: #{display.call(owner['agent'])} via #{harness.call(owner['harness'])}"
+  puts "Session: #{display.call(view['owner_session'])}"
+  puts "Heartbeat: #{view['heartbeat_at'] || 'none'}"
+  puts "Claims: #{claim_text.empty? ? 'none' : claim_text.join(', ')}"
+  if delegate
+    puts "Delegate: #{display.call(delegate['agent'])} via #{harness.call(delegate['harness'])}, #{display.call(delegate['status'])}"
+  else
+    puts "Delegate: none"
+  end
+  exit 0
+end
+
 intent_id = Bridge.intent_id_from_dir(dir)
 store = File.dirname(dir)
 name = File.basename(dir)
@@ -87,7 +134,10 @@ when "status"
   puts JSON.pretty_generate(report)
 when "fix"
   report = Bridge.repair_lock(key, intent_id: intent_id, intent_dir: dir,
-                              store: store, name: name)
+                              store: store, name: name, harness: harness,
+                              agent: opts[:agent], model: opts[:model], thread: opts[:thread],
+                              run_mode: opts[:mode],
+                              hint_harness: hint_harness)
   puts JSON.pretty_generate(report)
   unless report["status"] == "repaired"
     warn "plastic-lock: #{report['status']} by #{report['owner']}" \
@@ -108,23 +158,40 @@ when "release"
   end
   puts "released (#{result})"
 when "reclaim"
-  status, lock_data = Lock.takeover(dir, session: key)
+  status, lock_data = Lock.takeover(dir, session: key, harness: harness,
+                                    agent: opts[:agent], model: opts[:model],
+                                    thread: opts[:thread], run_mode: opts[:mode])
   if status == :fresh
     warn "plastic-lock: lock is FRESH and held by #{lock_data['owner_session']}; " \
          "back off (no silent reclaim)"
     exit 1
   end
   report = Bridge.repair_lock(key, intent_id: intent_id, intent_dir: dir,
-                              store: store, name: name)
+                              store: store, name: name, harness: harness,
+                              agent: opts[:agent], model: opts[:model], thread: opts[:thread],
+                              run_mode: opts[:mode],
+                              hint_harness: hint_harness)
   puts JSON.pretty_generate(report)
 when "delegate"
   usage! if opts[:delegate].nil?
-  ok = Lock.add_delegate(dir, delegate: opts[:delegate], session: key)
+  usage! if opts[:status] && !%w[finished failed].include?(opts[:status])
+  ok = if opts[:status]
+         Lock.update_delegate_status(dir, delegate: opts[:delegate],
+                                     status: opts[:status], session: key)
+       else
+         Lock.add_delegate(dir, delegate: opts[:delegate], session: key,
+                           harness: harness, agent: opts[:agent], model: opts[:model],
+                           thread: opts[:thread])
+       end
   unless ok
     warn "plastic-lock: only the lock owner may delegate; run plastic-lock status"
     exit 1
   end
-  puts "delegated #{opts[:delegate]} under #{key}"
+  if opts[:status]
+    puts "delegate #{opts[:delegate]} marked #{opts[:status]} under #{key}"
+  else
+    puts "delegated #{opts[:delegate]} under #{key}"
+  end
 when "claim"
   usage! if opts[:artifact].nil?
   status, data = Claim.acquire_claim(dir, opts[:artifact], session: key,

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

package/scripts/restore-intent-v1

@@ -45,6 +45,7 @@ require_relative "lib/store_discovery"
 require_relative "lib/intent_validator"
 require_relative "lib/graph_rebuild"
 require_relative "lib/frontmatter_writer"
+require_relative "lib/links_projection"
 require_relative "lib/restore_intent_v1"
 
 class RestoreIntentV1CLI
@@ -116,8 +117,18 @@ class RestoreIntentV1CLI
 
     other_files = prose_siblings_to_restore(dir)
 
+    # `## Links` is a purely derived section: apply_graph always re-derives new_md's body
+    # from v1_md's ORIGINAL (pre-reprojection) content, so its Links ENTRY LINES differ
+    # from the current, already-reprojected file on every single invocation, even when
+    # nothing else changed. Comparing raw new_md != current_md would treat that churn as a
+    # real change forever (write, reproject, write, reproject...), which is both pointless
+    # IO and, per D14, a false "something changed" signal. md_changed ignores only the
+    # entry lines themselves; any other difference (frontmatter graph, real prose) is
+    # still a real, detected change.
+    md_changed = differs_outside_links_entries?(new_md, current_md)
+
     prose_changes = other_files.keys.dup
-    prose_changes.unshift("#{base}.md") if new_md != current_md
+    prose_changes.unshift("#{base}.md") if md_changed
 
     puts RestoreIntentV1.render_report(
       base: base, at: at, prose_changes: prose_changes,
@@ -128,7 +139,7 @@ class RestoreIntentV1CLI
 
     return unless apply
 
-    File.write(md_path, new_md) if new_md != current_md
+    File.write(md_path, new_md) if md_changed
     other_files.each { |f, content| File.write(File.join(dir, f), content) }
 
     puts "Reminder: restore-to-v1 runs under the maintenance lock (PLASTIC.md > Terminal " \
@@ -136,7 +147,8 @@ class RestoreIntentV1CLI
 
     handle_links_reprojection(base)
     append_revision(dir, base, graph, files: prose_changes,
-                    before_sources: current_fm["sources"], before_chain: current_fm["chain"])
+                    before_sources: current_fm["sources"], before_chain: current_fm["chain"]) \
+      if md_changed || other_files.any?
   end
 
   private
@@ -261,6 +273,28 @@ class RestoreIntentV1CLI
          "Rerun: ruby #{project_links} --plastic-home #{plastic_home}"
   end
 
+  # True iff `md_a`/`md_b` differ OUTSIDE their ## Links ENTRY LINES (the ones
+  # LinksProjection renders/parses, plus its empty-state comment). Line-level, not
+  # section-level: a section-boundary replace (LinksSection.rewrite) would discard
+  # everything from the heading to EOF, which is unsafe here because a stray prose
+  # edit sitting after ## Links would be discarded too, not only the Links entries
+  # themselves. Frontmatter and every non-entry body line are compared verbatim, so a
+  # genuine graph or prose change is always still detected.
+  def differs_outside_links_entries?(md_a, md_b)
+    neutralize_links_entries(md_a) != neutralize_links_entries(md_b)
+  end
+
+  def neutralize_links_entries(text)
+    text.to_s.lines.map do |line|
+      stripped = line.chomp
+      if stripped.match?(LinksProjection::ENTRY_LINE_RE) || stripped == LinksProjection::EMPTY_COMMENT
+        "\n"
+      else
+        line
+      end
+    end.join
+  end
+
   def append_revision(dir, base, graph, files:, before_sources:, before_chain:)
     path = File.join(dir, "revisions.md")
     existing = File.exist?(path) ? File.read(path) : "# revisions.md\n\n"

package/scripts/sweep-store-worktrees

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# sweep-store-worktrees (intent 178, D2) -- ONE-TIME cleanup of the store
+# worktrees Plastic used to provision under `~/.plastic/.worktrees/` before
+# intent 178 retired the mechanism. Dry-run by default; nothing is ever
+# removed without an explicit --apply, run only after reviewing the dry-run
+# report (D2: "present a dry-run for owner review before applying").
+#
+# Usage:
+#   scripts/sweep-store-worktrees              # dry run (default, safe)
+#   scripts/sweep-store-worktrees --apply       # actually remove REMOVE candidates
+#   scripts/sweep-store-worktrees --home <dir>  # override plastic_home (tests/CI only)
+
+require_relative "lib/worktree_sweep"
+
+def parse_args(argv)
+  opts = { apply: false, home: Dir.home }
+  i = 0
+  while i < argv.length
+    case argv[i]
+    when "--apply" then opts[:apply] = true
+    when "--home"  then opts[:home] = argv[i += 1]
+    else
+      warn "sweep-store-worktrees: unknown argument #{argv[i].inspect}"
+      exit 1
+    end
+    i += 1
+  end
+  opts
+end
+
+def main(argv)
+  opts = parse_args(argv)
+  plastic_home = File.expand_path(File.join(opts[:home], ".plastic"))
+  unless Dir.exist?(File.join(plastic_home, ".worktrees"))
+    puts "No #{File.join(plastic_home, '.worktrees')} directory; nothing to sweep."
+    exit 0
+  end
+
+  candidates = WorktreeSweep.candidates(plastic_home: plastic_home)
+  puts WorktreeSweep.dry_run_report(candidates)
+
+  if opts[:apply]
+    removed = WorktreeSweep.apply!(candidates, plastic_home: plastic_home)
+    puts ""
+    puts "Removed #{removed.length} worktree(s):"
+    removed.each { |c| puts "  #{c.name}" }
+  end
+end
+
+main(ARGV) if $PROGRAM_NAME == __FILE__