@zalom/plastic 2.0.0-alpha.9 → 2.0.2

package/scripts/node-transition

@@ -0,0 +1,291 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "time"
+require_relative "lib/savepoint"
+require_relative "lib/node_ledger"
+require_relative "lib/ready_set"
+require_relative "lib/guarded_append"
+require_relative "lib/lock"
+require_relative "lib/arm"
+
+# node-transition - the CLI over NodeLedger that REFUSES what the graph does not
+# allow (intent 335, G2). An orchestrator can run this by hand today, before the
+# runner (intent 340) exists.
+#
+# Usage:
+#   node-transition <intent_dir> --node <id|Intent> --state <state> [--field k=v]...
+#                    [--comment "..."] [--needs a,b] [--session SID] [--now ISO8601]
+#   node-transition report <intent_dir>
+#
+# Exit codes (spec D18, matching the tree: scripts/append-ledger:125 uses 3 for a
+# guard that could not be taken, scripts/end-intent:675 uses 4 for a lock-ownership
+# refusal):
+#   0 - the line was appended
+#   2 - usage: not an intent directory, bad subject, unknown state, missing
+#       required field, a tab or newline in a value
+#   3 - the ledger guard was unavailable; nothing was written
+#   4 - running, and the caller does not hold delivery.lock
+#   5 - running, and the subject is not ready
+#   6 - reclaimed, and the subject's last running line has not expired
+module NodeTransition
+  module_function
+
+  # The readiness precondition for `running` (intent 336, G3): ReadySet.ready?
+  # applied to `subject` against `edges`/`nodes` already parsed once, before
+  # the guard is ever taken (spec: "parsed once, before the guard"). Takes
+  # `content` (the ledger's raw text), never a path, so this method can be run
+  # twice: once as a cheap unguarded pre-check for a fast, readable refusal,
+  # and once - the AUTHORITATIVE decision - as the guard's precondition,
+  # evaluated against the exact content GuardedAppend just read under its
+  # lock hold (post-execution review row 7.1, carried forward by 336). A
+  # path-based re-read here would defeat the guard: two callers could each
+  # open their own handle, both see "planned", and both go on to append
+  # `running`.
+  def running_ready?(content, subject, edges, nodes, caps: ReadySet::DEFAULT_CAPS)
+    ReadySet.ready?(content: content, subject: subject, graph: { edges: edges }, nodes: nodes, caps: caps)
+  end
+
+  # graph.md and nodes/ for `subject`'s readiness (intent 336, G3): a genuinely
+  # missing graph.md degrades gracefully to no known needs/kind/files (the
+  # same fallback the temporary needs_from_graph reader gave, so a legacy
+  # intent with no graph.md still dispatches ad hoc node ids), while a
+  # PRESENT but broken graph.md (no ## Graph section, a cycle) is a clean
+  # refusal, never a raise - {edges:, nodes:, error:}.
+  def resolve_graph_and_nodes(intent_dir)
+    graph_path = File.join(intent_dir, "graph.md")
+    return { edges: {}, nodes: {}, error: nil } unless File.exist?(graph_path)
+
+    loaded = ReadySet.load_graph(intent_dir)
+    return { edges: loaded[:edges] || {}, nodes: loaded[:nodes] || {}, error: nil } if loaded[:ok]
+
+    { edges: {}, nodes: {}, error: loaded[:errors].join("; ") }
+  end
+
+  # Session resolution per spec D16: an explicit --session is authoritative and
+  # NEVER falls through (an explicit non-owner is refused outright, never
+  # silently granted ownership through a fallback). Without it, try the
+  # environment's CLAUDE_CODE_SESSION_ID, then the derived `auto-` key, and keep
+  # the first candidate that actually HOLDS the lock (owner or delegate,
+  # Lock.holds?) - so the fallback can never grant ownership to a session that
+  # does not have it.
+  def resolve_owning_session(intent_dir, explicit:, env_session:)
+    if explicit && !explicit.to_s.strip.empty?
+      return Lock.holds?(intent_dir, session: explicit) ? explicit : nil
+    end
+
+    store = Arm.store_for(intent_dir)
+    intent_id = Arm.intent_id_for(intent_dir)
+    candidates = [env_session, Arm.derive_key(store, intent_id)].reject { |c| c.to_s.strip.empty? }
+    candidates.find { |c| Lock.holds?(intent_dir, session: c) }
+  end
+
+  def intent_directory?(dir)
+    dir && File.directory?(dir) && File.exist?(Savepoint.intent_file(dir))
+  end
+
+  def valid_subject?(subject)
+    subject == Savepoint::INTENT_SUBJECT || subject.to_s.match?(Savepoint::NODE_SUBJECT_RE)
+  end
+
+  def opt(args, name)
+    (i = args.index(name)) && args[i + 1]
+  end
+
+  def opt_all(args, name)
+    args.each_index.select { |i| args[i] == name }.map { |i| args[i + 1] }
+  end
+
+  def parse_fields(args)
+    opt_all(args, "--field").each_with_object({}) do |pair, memo|
+      key, value = pair.to_s.split("=", 2)
+      memo[key] = value if key && !key.empty?
+    end
+  end
+
+  def usage
+    warn "Usage: node-transition <intent_dir> --node <id|Intent> --state <state> " \
+         "[--field k=v]... [--comment \"...\"] [--needs a,b] [--session SID] [--now ISO8601]"
+    warn "       node-transition report <intent_dir>"
+  end
+
+  def run_report(intent_dir)
+    unless intent_directory?(intent_dir)
+      warn "node-transition: #{intent_dir.inspect} is not an intent directory"
+      usage
+      exit 2
+    end
+
+    savepoint_path = File.join(intent_dir, "savepoint.md")
+    anomalies = NodeLedger.anomalies(savepoint_path)
+    if anomalies.empty?
+      puts "node-transition report: no torn or unattributed transition lines"
+    else
+      anomalies.each { |a| puts "#{a[:reason]}: #{a[:line]}" }
+    end
+    exit 0
+  end
+
+  def main(argv)
+    args = argv.dup
+    head = args.shift
+
+    if head == "report"
+      report_dir_arg = args.shift
+      run_report(report_dir_arg && File.expand_path(report_dir_arg))
+      return
+    end
+
+    intent_dir_arg = head
+    unless intent_directory?(intent_dir_arg && File.expand_path(intent_dir_arg))
+      warn "node-transition: #{intent_dir_arg.inspect} is not an intent directory"
+      usage
+      exit 2
+    end
+    intent_dir = File.expand_path(intent_dir_arg)
+
+    subject = opt(args, "--node")
+    state = opt(args, "--state")
+    comment = opt(args, "--comment")
+    needs_flag = opt(args, "--needs")
+    session_flag = opt(args, "--session")
+    now_flag = opt(args, "--now")
+    fields = parse_fields(args)
+
+    if subject.nil? || state.nil?
+      warn "node-transition: --node and --state are required"
+      usage
+      exit 2
+    end
+
+    unless valid_subject?(subject)
+      warn "node-transition: #{subject.inspect} is neither #{Savepoint::INTENT_SUBJECT} nor a valid node id"
+      exit 2
+    end
+
+    unless NodeLedger::STATES.include?(state)
+      warn "node-transition: unknown state #{state.inspect}"
+      exit 2
+    end
+
+    now = begin
+      now_flag ? Time.iso8601(now_flag) : Time.now
+    rescue ArgumentError
+      warn "node-transition: --now must be ISO 8601"
+      exit 2
+    end
+
+    begin
+      fields.each_value { |v| NodeLedger.normalize_value(v) }
+      NodeLedger.normalize_value(comment) if comment
+    rescue ArgumentError => e
+      warn "node-transition: #{e.message}"
+      exit 2
+    end
+
+    missing = NodeLedger.missing_fields(state, fields)
+    unless missing.empty?
+      warn "node-transition: state #{state} requires #{missing.join(', ')}"
+      exit 2
+    end
+
+    savepoint_path = File.join(intent_dir, "savepoint.md")
+    precondition = nil
+
+    case state
+    when "running"
+      owning_session = resolve_owning_session(intent_dir, explicit: session_flag,
+                                                            env_session: ENV["CLAUDE_CODE_SESSION_ID"])
+      unless owning_session
+        warn "node-transition: the caller does not hold delivery.lock for #{intent_dir}"
+        exit 4
+      end
+
+      if subject == Savepoint::INTENT_SUBJECT
+        # The node readiness rule (four conditions over the work graph) is
+        # scoped to node subjects; the intent-scope subject is never gated by
+        # it, so a legacy intent with no graph.md at all can still write an
+        # Intent line (spec Acceptance Criteria; matrix "Transition the
+        # Intent subject").
+        precondition = nil
+      else
+        resolved = resolve_graph_and_nodes(intent_dir)
+        if resolved[:error]
+          warn "node-transition: #{resolved[:error]}"
+          exit 5
+        end
+
+        needs_override = needs_flag ? needs_flag.split(",").map(&:strip).reject(&:empty?) : nil
+        edges = needs_override ? resolved[:edges].merge(subject => needs_override) : resolved[:edges]
+        nodes = resolved[:nodes]
+
+        # Fast, unguarded pre-check: a cheap, readable refusal for the common
+        # case, but NEVER the authoritative decision (post-execution review
+        # row 7.1, carried forward by 336). The authoritative check is the
+        # `precondition` below, run inside GuardedAppend's lock hold against
+        # the content it actually read. `edges` and `nodes` are parsed once,
+        # above, before the guard is ever taken (spec D1).
+        precheck_content = File.exist?(savepoint_path) ? File.read(savepoint_path) : ""
+        result = running_ready?(precheck_content, subject, edges, nodes)
+        unless result[:ready]
+          warn "node-transition: #{result[:blockers].join('; ')}"
+          exit 5
+        end
+
+        precondition = ->(content) { running_ready?(content, subject, edges, nodes)[:ready] }
+      end
+    when "reclaimed"
+      running_entry = NodeLedger.last_running(savepoint_path, subject)
+      unless running_entry
+        warn "node-transition: #{subject} has no running line to reclaim"
+        exit 6
+      end
+
+      # Post-execution review row 7.4: expiry alone is not enough. A `done`
+      # node whose last `running` line's expires= happens to be in the past
+      # must not revert to `planned` and become re-dispatchable - reclaim is
+      # deliberately lock-free (spec D43), so this status check is the only
+      # thing that stops it. Row 7.5 pins that a genuinely running, expired
+      # subject is still reclaimable, so the crash sweep keeps working.
+      current_status = NodeLedger.status_for(savepoint_path, subject)
+      unless current_status == "running"
+        warn "node-transition: #{subject} is #{current_status}, not running; nothing to reclaim"
+        exit 6
+      end
+
+      expires_raw = (running_entry[:fields] || {})["expires"]
+      expiry_time = begin
+        expires_raw && Time.iso8601(expires_raw)
+      rescue ArgumentError
+        nil
+      end
+
+      unless expiry_time && now > expiry_time
+        warn "node-transition: #{subject}'s running line has not expired yet"
+        exit 6
+      end
+    end
+
+    result = begin
+      NodeLedger.append_transition(savepoint_path, subject: subject, state: state, fields: fields,
+                                    comment: comment, now: now, precondition: precondition)
+    rescue GuardedAppend::Unavailable => e
+      warn "node-transition: #{e.message}"
+      exit 3
+    rescue ArgumentError => e
+      warn "node-transition: #{e.message}"
+      exit 2
+    end
+
+    if result == :refused
+      warn "node-transition: #{subject} was no longer ready by the time the write lock was taken"
+      exit 5
+    end
+
+    puts "node-transition: appended #{state} for #{subject}"
+    exit 0
+  end
+end
+
+NodeTransition.main(ARGV) if $PROGRAM_NAME == __FILE__

package/scripts/outcome-report

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# outcome-report - the CLI over scripts/lib/outcome_report.rb (intent 339, G6).
+# Prints the generated outcome.md by default; --write puts it on disk through
+# AtomicWrite. `end-intent` calls the library directly (never shells out to
+# this), so this command is for a human or an agent checking the generated
+# report before or instead of a close.
+#
+# Usage:
+#   outcome-report <intent_dir> [--write] [--disposition delivered|abandoned]
+#
+# Exit codes:
+#   0 - printed (or written) successfully
+#   2 - usage error: no path given, an unknown flag, or the path is not an
+#       intent directory
+#   3 - the report model could not be built (a malformed or absent graph.md)
+
+require_relative "lib/outcome_report"
+require_relative "lib/intent_screen"
+require_relative "lib/outcome_guard"
+
+def usage_abort(message)
+  warn "outcome-report: #{message}"
+  exit 2
+end
+
+args = ARGV.dup
+write_flag = false
+disposition = "delivered"
+positional = []
+
+while (arg = args.shift)
+  case arg
+  when "--write"
+    write_flag = true
+  when "--disposition"
+    disposition = args.shift or usage_abort("--disposition needs a value")
+  else
+    usage_abort("unknown flag #{arg.inspect}") if arg.start_with?("--")
+    positional << arg
+  end
+end
+
+target = positional.first
+usage_abort("usage: outcome-report <intent_dir> [--write] [--disposition delivered|abandoned]") unless target
+# Row v1f.9 (N3): refuse an unknown --disposition here rather than write a
+# record OutcomeGuard then refuses. OutcomeGuard::DISPOSITIONS is already
+# loaded in-process, so this is one comparison, not a duplicated list.
+unless OutcomeGuard::DISPOSITIONS.include?(disposition)
+  usage_abort("--disposition must be one of #{OutcomeGuard::DISPOSITIONS.join('|')}, got #{disposition.inspect}")
+end
+
+intent_dir = File.expand_path(target)
+usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
+
+model = OutcomeReport.model(intent_dir)
+unless model[:ok]
+  warn "outcome-report: the report model could not be built: #{model[:errors].join('; ')}"
+  exit 3
+end
+
+if write_flag
+  OutcomeReport.write(intent_dir, disposition: disposition)
+  puts File.join(intent_dir, "outcome.md")
+else
+  outcome_path = File.join(intent_dir, "outcome.md")
+  existing = File.exist?(outcome_path) ? File.read(outcome_path) : nil
+  puts OutcomeReport.render(model, disposition: disposition, existing: existing,
+                                   findings: OutcomeReport.findings(intent_dir), intent_dir: intent_dir)
+end
+
+exit 0

package/scripts/plastic-lock

@@ -15,16 +15,16 @@
 #   arm           take the intent for this session (intent 307): acquire
 #                 delivery.lock stamped with --mode (default auto) and the
 #                 provenance flags, provision the code worktree, and point the
-#                 session at the intent; exit 1 on a held, stale, excluded, or
-#                 corrupt lock with the resolving doctor hint
+#                 session at the intent; exit 3 on a held, stale, or excluded
+#                 lock (another owner's), exit 1 on a corrupt one, each with the
+#                 public command that resolves it
 #   who           compact, read-only durable owner/activity view
 #   status        report the lock file, its freshness, the derived worktree,
-#                 whether this session's pointer names the intent, and any
-#                 live per-artifact claims
+#                 whether this session is the one delivering the intent, and
+#                 any live per-artifact claims
 #   fix           idempotent repair of the lock for the current session; never
 #                 touches a fresh foreign lock
-#   release       owner clears the lock and points the session back at the day
-#                 ledger (End tail / abandoning a boarding)
+#   release       owner clears the lock (End tail / abandoning a boarding)
 #   reclaim       explicit takeover of a stale lock, audited in savepoint.md
 #   delegate      owner registers a subagent session under the lock (D4)
 #   claim         acquire the named --artifact's claim token (intent 111);
@@ -32,18 +32,20 @@
 #                 including this same session; takes over a stale claim
 #   release-claim free the named --artifact's claim token
 #
-# Without --intent-dir the intent is resolved from this session's pointer
-# (~/.plastic/store/.tmp/<session>/current) when it names an intent id, looked
-# up in the working directory's project store and then the global store. The
-# /tmp bridge JSON this CLI used to resolve through was removed in 2.0
-# (intent 307). Exit 0 on success/report; exit 1 when the verb is blocked.
+# Without --intent-dir the intent is resolved from this session's held
+# delivery lock (ActiveDelivery.resolve over the global store and the
+# configured project roots): exactly one fresh lock this session owns or
+# delegates for. Session resolution no longer reads any per-session state
+# file; that path was retired in 2.0 (intent 307) and 344 G11.
+# Exit 0 on success/report; exit 3 when another session owns the lock (arm,
+# fix, release, reclaim); exit 1 when the verb is otherwise blocked.
 
+require_relative "lib/store_layout"
 require "json"
 require "yaml"
-require_relative "lib/bridge"
 require_relative "lib/lock"
 require_relative "lib/arm"
-require_relative "lib/session_ledger"
+require_relative "lib/active_delivery"
 
 VERBS = %w[arm status who fix release reclaim delegate claim release-claim].freeze
 
@@ -70,6 +72,7 @@ until ARGV.empty?
   when "--model" then opts[:model] = ARGV.shift
   when "--thread" then opts[:thread] = ARGV.shift
   when "--mode" then opts[:mode] = ARGV.shift
+  when "--allow-inline" then opts[:allow_inline] = true
   when "--status" then opts[:status] = ARGV.shift
   else
     warn "unknown flag #{flag}"
@@ -81,22 +84,12 @@ 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"
 # The plastic home every hook uses (PLASTIC_HOME, else ~/.plastic); Arm takes the
 # OS home above it, the same convention Worktree resolves projects.yml from.
 plastic_home_env = ENV["PLASTIC_HOME"].to_s.strip
 home = plastic_home_env.empty? ? Dir.home : File.dirname(File.expand_path(plastic_home_env))
 
-# The stores this session's pointer is resolved against: the project store of
-# the working directory (projects.yml, longest path match), then the global one.
-def candidate_stores(home, cwd)
-  plastic_home = File.join(home, ".plastic")
-  stores = []
-  slug = SessionLedger.project_slug(cwd, plastic_home: plastic_home)
-  stores << File.join(plastic_home, "projects", slug, "store") if slug && slug != "global"
-  stores << File.join(plastic_home, "store")
-  stores
-end
+plastic_home = File.join(home, ".plastic")
 
 dir = opts[:dir]
 if dir.nil? || dir.strip.empty?
@@ -104,11 +97,21 @@ if dir.nil? || dir.strip.empty?
     warn "plastic-lock: #{verb} needs --intent-dir <intent dir>"
     exit 1
   end
-  dir = Arm.intent_dir_from_pointer(session, home: home, stores: candidate_stores(home, Dir.pwd))
-end
-if dir.nil?
-  warn "plastic-lock: no intent resolved; pass --intent-dir <intent dir>"
-  exit 1
+  roots = ActiveDelivery.project_roots(plastic_home)
+  global_store = Plastic::StoreLayout.global_store(plastic_home)
+  dir = ActiveDelivery.resolve(global_store: global_store, project_roots: roots, session: session)
+  if dir.nil?
+    candidates = ActiveDelivery.candidate_intent_dirs(global_store: global_store, project_roots: roots).uniq
+    held = candidates.select do |candidate|
+      Lock.fresh?(candidate) && Lock.holds?(candidate, session: session)
+    end
+    if held.size > 1
+      warn "plastic-lock: more than one held delivery lock names this session; pass --intent-dir <intent dir>"
+    else
+      warn "plastic-lock: no intent resolved; pass --intent-dir <intent dir>"
+    end
+    exit 1
+  end
 end
 dir = File.expand_path(dir)
 
@@ -143,45 +146,54 @@ if verb == "who"
   exit 0
 end
 
-intent_id = Bridge.intent_id_from_dir(dir)
+intent_id = Arm.intent_id_for(dir)
 store = File.dirname(dir)
 key = Arm.resolve_session(session, store: store, intent_id: intent_id)
 
-def doctor_hint(verb_text, harness)
-  "run #{Lock.skill_ref('plastic-doctor', harness: harness)} #{verb_text}"
+# Exit 3 is Plastic's refusal: the lock belongs to another session, and only
+# its owner (or the person who owns the work) may resolve it.
+def refuse(message)
+  warn "plastic-lock: #{message}"
+  exit 3
 end
 
 case verb
 when "arm"
   result = Arm.arm(intent_dir: dir, session: key, mode: opts[:mode] || "auto", home: home,
-                   harness: harness, agent: opts[:agent], model: opts[:model], thread: opts[:thread])
+                   harness: harness, agent: opts[:agent], model: opts[:model], thread: opts[:thread],
+                   allow_inline: opts[:allow_inline] || false)
   case result[:status]
   when :acquired, :owned
     wt = result[:worktree] || {}
     puts JSON.pretty_generate(
       "intent_dir" => dir, "session" => result[:session], "status" => result[:status].to_s,
       "run_mode" => result[:lock] && result[:lock]["run_mode"],
-      "worktree" => wt, "pointer" => result[:pointer]
+      "worktree" => wt
     )
   when :held
-    warn "plastic-lock: delivery lock for intent #{intent_id} is held by session " \
-         "#{result[:lock] && result[:lock]['owner_session']}; #{doctor_hint('check the lock status', hint_harness)}"
-    exit 1
+    refuse "delivery lock for intent #{intent_id} is held by session " \
+           "#{result[:lock] && result[:lock]['owner_session']}; plastic auto lock status #{intent_id} shows it"
   when :stale
-    warn "plastic-lock: delivery lock for intent #{intent_id} is stale (owner " \
-         "#{result[:lock] && result[:lock]['owner_session']}); #{doctor_hint('reclaim the lock to take it over with an audit', hint_harness)}"
-    exit 1
+    refuse "delivery lock for intent #{intent_id} is stale (owner " \
+           "#{result[:lock] && result[:lock]['owner_session']}); #{Arm.stale_hint(intent_id)}"
   when :excluded
-    warn "plastic-lock: a #{result[:lock] && result[:lock]['type']} lock is active on intent " \
-         "#{intent_id}; #{doctor_hint('check the lock status', hint_harness)}"
-    exit 1
+    refuse "a #{result[:lock] && result[:lock]['type']} lock is active on intent " \
+           "#{intent_id}; plastic auto lock status #{intent_id} shows it"
   when :corrupt
-    warn "plastic-lock: delivery.lock for intent #{intent_id} is unreadable; #{doctor_hint('fix the lock', hint_harness)}"
+    warn "plastic-lock: delivery.lock for intent #{intent_id} is unreadable; plastic auto lock fix #{intent_id} rewrites it"
     exit 1
+  when :inline_refused
+    warn "plastic-lock: refusing to arm intent #{intent_id} from a conversation session " \
+         "(owner rule 2026-08-31: no inline intent delivery). Dispatch the delivery team " \
+         "instead (plastic-auto), or pass --allow-inline with explicit owner approval."
+    exit 3
   end
 when "status"
   lock = Lock.read(dir)
-  pointer = Arm.read_pointer(key, home: home)
+  resolved = ActiveDelivery.resolve(global_store: Plastic::StoreLayout.global_store(plastic_home),
+                                    project_roots: ActiveDelivery.project_roots(plastic_home),
+                                    session: key)
+  delivering = !resolved.nil? && File.expand_path(resolved) == File.expand_path(dir)
   report = {
     "intent_dir" => dir,
     "session" => key,
@@ -189,41 +201,34 @@ when "status"
     "lock_fresh" => Lock.fresh?(dir),
     "lock_corrupt" => Lock.corrupt?(dir),
     "worktree" => Arm.worktree_block(intent_dir: dir, home: home),
-    "pointer" => pointer,
-    "pointer_names_intent" => pointer == intent_id,
+    "delivering" => delivering,
     "claims" => Claim.claims_status(dir),
   }
   puts JSON.pretty_generate(report)
 when "fix"
   report = Arm.repair(intent_dir: dir, session: key, home: home, harness: harness,
                       agent: opts[:agent], model: opts[:model], thread: opts[:thread],
-                      run_mode: opts[:mode], hint_harness: hint_harness)
+                      run_mode: opts[:mode])
   puts JSON.pretty_generate(report)
   unless report["status"] == "repaired"
-    warn "plastic-lock: #{report['status']} by #{report['owner']}" \
-         "#{report['hint'] ? " (#{report['hint']})" : ''}"
-    exit 1
+    refuse "#{report['status']} by #{report['owner']}" \
+           "#{report['hint'] ? " (#{report['hint']})" : ''}"
   end
 when "release"
   result = Lock.release(dir, session: key)
-  if result == :not_owner
-    warn "plastic-lock: not the owner; run plastic-lock status"
-    exit 1
-  end
-  Arm.reset_pointer(key, intent_id, home: home)
+  refuse "not the owner; plastic auto lock status #{intent_id} shows who is" if result == :not_owner
   puts "released (#{result})"
 when "reclaim"
   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
+    refuse "lock is FRESH and held by #{lock_data['owner_session']}; " \
+           "back off (no silent reclaim)"
   end
   report = Arm.repair(intent_dir: dir, session: key, home: home, harness: harness,
                       agent: opts[:agent], model: opts[:model], thread: opts[:thread],
-                      run_mode: opts[:mode], hint_harness: hint_harness)
+                      run_mode: opts[:mode])
   puts JSON.pretty_generate(report)
 when "delegate"
   usage! if opts[:delegate].nil?

package/scripts/project-links

@@ -48,10 +48,6 @@ require_relative "lib/revisions_writer"
 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,
                  drop_unbacked_links: false, intent: nil, store: nil)
     @plastic_home = plastic_home
@@ -60,20 +56,7 @@ class ProjectLinks
     @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`
-    # 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
+    @audit_path = audit_path || File.join(Plastic::StoreLayout.global_root(plastic_home), "resources", "audit--links-projection.md")
   end
 
   attr_reader :plastic_home, :dry_run, :audit_path, :drop_unbacked_links, :intent, :store
@@ -330,9 +313,11 @@ class ProjectLinks
     "(ambiguous: multiple ## Links headings)"
   end
 
-  # Always write the audit (even in dry-run, so the human reviews the plan).
+  # Return the audit for previews; save it only when applying changes.
   def emit_audit(store_list, results)
     text = render_audit(store_list, results)
+    return text if dry_run
+
     FileUtils.mkdir_p(File.dirname(audit_path))
     File.write(audit_path, text)
     text
@@ -348,7 +333,7 @@ class ProjectLinks
 
   def render_audit(store_list, results)
     lines = []
-    lines << "# Audit: store-wide ## Links projection (intent 72)"
+    lines << "# Audit: store-wide Links projection"
     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
@@ -482,6 +467,6 @@ if $PROGRAM_NAME == __FILE__
        "regenerated #{totals[:regenerated]}, added #{totals[:added]}, " \
        "unchanged #{totals[:unchanged]}, failed #{totals[:failed]} " \
        "across #{results.size} store(s)."
-  puts "Audit: #{tool.audit_path}"
+  puts(dry ? "Dry run: no files written." : "Audit: #{tool.audit_path}")
   exit 1 if tool.any_failed?(results)
 end