@zalom/plastic 1.4.0 → 1.5.0

package/scripts/lib/maintenance_git.rb

@@ -0,0 +1,94 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "open3"
+
+# MaintenanceGit - git isolation for a maintenance action (intent 197, D12/D13): a fresh
+# branch off the CURRENT tip of `base`, the caller's block runs, only the paths the block
+# ACTUALLY changed are staged (never `git add -A`), committed, and the branch is merged back
+# to `base` as part of the SAME closed operation before this method returns. Nothing strands
+# on an unmerged branch; nothing outside the block's own change is ever touched.
+#
+# Requires a CLEAN working tree before starting (see module doc above for why); refuses
+# loudly rather than attempt to distinguish pre-existing dirt from the block's own changes.
+# On any error inside the block, the working tree is hard-reset and returned to `base` before
+# re-raising, which is SAFE only because the precondition already proved nothing else was
+# dirty when the branch was created.
+module MaintenanceGit
+  module_function
+
+  class NotAGitRepo < StandardError; end
+  class DirtyWorkingTree < StandardError; end
+
+  def git_toplevel(dir)
+    out, _err, status = Open3.capture3("git", "-C", dir, "rev-parse", "--show-toplevel")
+    return nil unless status.success?
+
+    top = out.strip
+    top.empty? ? nil : top
+  end
+
+  # Bare paths (status prefix stripped), relative to `root`. Empty array on a clean tree.
+  def porcelain_paths(root)
+    out, _err, status = Open3.capture3("git", "-C", root, "status", "--porcelain")
+    return [] unless status.success?
+
+    out.lines.map { |l| l[3..].to_s.strip }.reject(&:empty?)
+  end
+
+  # Runs `block` inside a fresh branch off `base`'s current tip. Returns
+  # { changed: [...], committed: bool, merged: bool, branch: name }.
+  def run_scoped(repo_dir:, branch_name:, commit_message:, base: "main")
+    root = git_toplevel(repo_dir)
+    raise NotAGitRepo, "#{repo_dir} is not inside a git repository" unless root
+
+    dirty = porcelain_paths(root)
+    unless dirty.empty?
+      raise DirtyWorkingTree,
+            "#{root} has #{dirty.size} uncommitted path(s) before maintenance started; " \
+            "commit or stash them first (never swept via git add -A): #{dirty.join(", ")}"
+    end
+
+    checkout!(root, base)
+    run_git!(root, "checkout", "--quiet", "-b", branch_name)
+
+    begin
+      yield
+    rescue StandardError
+      run_git!(root, "reset", "--hard", "--quiet")
+      run_git!(root, "clean", "-fd", "--quiet")
+      checkout!(root, base)
+      delete_branch(root, branch_name)
+      raise
+    end
+
+    changed = porcelain_paths(root)
+    if changed.empty?
+      checkout!(root, base)
+      delete_branch(root, branch_name)
+      return { changed: [], committed: false, merged: false, branch: branch_name }
+    end
+
+    run_git!(root, "add", "--", *changed)
+    run_git!(root, "-c", "user.name=Plastic", "-c", "user.email=plastic@localhost",
+             "commit", "--quiet", "-m", commit_message)
+    checkout!(root, base)
+    run_git!(root, "merge", "--quiet", "--no-ff", "-m", "Merge #{branch_name} into #{base}", branch_name)
+    delete_branch(root, branch_name)
+
+    { changed: changed, committed: true, merged: true, branch: branch_name }
+  end
+
+  def checkout!(root, ref)
+    run_git!(root, "checkout", "--quiet", ref)
+  end
+
+  def delete_branch(root, name)
+    Open3.capture3("git", "-C", root, "branch", "--quiet", "-D", name)
+  end
+
+  def run_git!(root, *args)
+    _out, err, status = Open3.capture3("git", "-C", root, *args)
+    raise "git #{args.join(" ")} failed in #{root}: #{err}" unless status.success?
+  end
+end

package/scripts/lib/revisions_writer.rb

@@ -0,0 +1,69 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# RevisionsWriter - the shared append-only revisions.md writer (intent 107's convention,
+# generalized from restore_intent_v1.rb's proven pattern, intent 197). Every tool that
+# performs structural maintenance on an intent (project-links, rebuild-graph,
+# restore-intent-v1) must record it here: PLASTIC.md's `revisions.md` contract is that a
+# structural change and its receipt are never separated. This module owns rendering ONE
+# entry's text and appending it correctly; it does no git operations (that is
+# lib/maintenance_git.rb's job) and never overwrites a prior entry.
+#
+# Pure where it can be (render_entry has no IO); the IO half (append!) is a thin,
+# dependency-free file read/write, matching every other tool in scripts/lib.
+module RevisionsWriter
+  module_function
+
+  # PURE. Renders one `## Revision vN - TIMESTAMP` entry in the documented shape
+  # (PLASTIC-reference.md > Structural maintenance and revisions.md; templates/revisions.md).
+  # `n` is the next revision number (caller resolves it via next_revision_number, or a caller
+  # that already knows it, e.g. a batch writer amortizing one file read across many entries).
+  # `why` is the one-sentence reason ending in "[rule: <tag>]" (tag is appended here if the
+  # caller passes a bare sentence plus `rule:`, so every caller cannot forget the tag).
+  # `prior_location` and `change` are free text (the "Change:" line for a metadata edit, or a
+  # multi-line indented "Content held:" block for a relocated section/file - callers building
+  # a Content-held entry should pass an already-indented `change` block).
+  def render_entry(n, why:, rule:, prior_location:, change:, timestamp: Time.now.utc)
+    ts = timestamp.strftime("%Y-%m-%d-%H:%M")
+    lines = []
+    lines << "## Revision v#{n} - #{ts}"
+    lines << "- Why: #{why.to_s.strip} [rule: #{rule}]"
+    lines << "- Prior location: #{prior_location}"
+    lines << "- Change: #{change}"
+    "#{lines.join("\n")}\n"
+  end
+
+  # PURE. Every existing "## Revision vN" number found in `existing_text` (empty array when
+  # none, i.e. the file does not exist yet or carries no entries). Mirrors
+  # scripts/restore-intent-v1's own `nums = existing.scan(/^## Revision v(\d+)/)` exactly, so
+  # the two writers can never disagree about numbering.
+  def revision_numbers(existing_text)
+    existing_text.to_s.scan(/^## Revision v(\d+)/).flatten.map(&:to_i)
+  end
+
+  def next_revision_number(existing_text)
+    (revision_numbers(existing_text).max || 0) + 1
+  end
+
+  # IO. Appends one entry to `<intent_dir>/revisions.md`, creating the file with its
+  # documented header (matching templates/revisions.md's "# revisions.md" title line) if it
+  # does not exist yet. NEVER overwrites or reorders a prior entry (append-only, intent 124's
+  # own v3-corrects-v2-by-appending precedent). Returns the revision number written.
+  #
+  # Raises RevisionsWriter::WriteFailed on any IO error (permission, disk full, read-only
+  # filesystem) so a caller can roll back a paired structural change rather than leave it
+  # unrecorded (D14's "or refuse"). Never swallows an error silently.
+  def append!(intent_dir, why:, rule:, prior_location:, change:, timestamp: Time.now.utc)
+    path = File.join(intent_dir, "revisions.md")
+    existing = File.exist?(path) ? File.read(path) : "# revisions.md\n\n"
+    n = next_revision_number(existing)
+    entry = render_entry(n, why: why, rule: rule, prior_location: prior_location,
+                         change: change, timestamp: timestamp)
+    File.write(path, "#{existing.chomp}\n\n#{entry}")
+    n
+  rescue StandardError => e
+    raise WriteFailed, "could not append revisions.md at #{path}: #{e.message}"
+  end
+
+  class WriteFailed < StandardError; end
+end

package/scripts/lib/worktree.rb

@@ -18,9 +18,11 @@ require_relative "lock"
 # projects.yml and runs `git -C <repo> worktree add`, so the cwd-not-root bug
 # dies by construction (decision D6).
 #
-# Two worktrees per project intent, both named `{id}--{slug}` (decision D2):
-#   code  worktree  <repo>/.claude/worktrees/{id}--{slug}  branch plastic/{id}--{slug}
-#   store worktree  <plastic_home>/.worktrees/{id}--{slug} branch plastic-store/{id}--{slug}
+# One worktree per project intent (decision D2, retired to a single worktree by
+# intent 178): the code worktree, <repo>/.claude/worktrees/{id}--{slug}, branch
+# plastic/{id}--{slug}. Store-write safety for lifecycle-doc writes now comes
+# from intent 197's branch-from-main plus scoped-commit mechanism instead of a
+# second, dedicated worktree (see PLASTIC.md's worktree doctrine).
 #
 # The durable delivery.lock file in the intent dir is the single-owner
 # delivery lock (intent 108): session-keyed, lease-based, explicit takeover.
@@ -60,22 +62,21 @@ module Worktree
     "#{intent_id}--#{intent_slug}"
   end
 
-  # Pure, deterministic. Returns the four paths/branches. No git calls.
+  # Pure, deterministic. Returns the code worktree's path/branch. No git calls.
   # `repo_path` is resolved from projects.yml when nil; when it cannot be
   # resolved the code worktree path/branch are nil (a global-store-only intent).
+  # Store-worktree provisioning was retired by intent 178: this used to also
+  # return a `store`/`store_branch` pair for a second worktree under
+  # `<plastic_home>/.worktrees/{id}--{slug}`; nothing provisions that anymore.
   def paths(slug:, intent_id:, intent_slug:, home: Dir.home, repo_path: nil)
     name = dir_name(intent_id, intent_slug)
     repo = repo_path || repo_for(slug, home: home)
-    plastic_home = File.expand_path(File.join(home, ".plastic"))
 
     code_path = repo ? File.join(File.expand_path(repo), ".claude", "worktrees", name) : nil
-    store_path = File.join(plastic_home, ".worktrees", name)
 
     {
       "code" => code_path,
       "code_branch" => code_path ? "plastic/#{name}" : nil,
-      "store" => store_path,
-      "store_branch" => "plastic-store/#{name}",
     }
   end
 
@@ -133,28 +134,16 @@ module Worktree
     block = {
       "code" => nil,
       "code_branch" => nil,
-      "store" => p["store"],
-      "store_branch" => p["store_branch"],
       "provisioned" => false,
     }
 
     plastic_home = File.expand_path(File.join(home, ".plastic"))
 
-    # Gitignore safety (intent 73c3): the store worktrees live under the store git
-    # repo, so without ignoring `.worktrees/` a `git add -A` sweeps their gitlinks
-    # into the store commit. Ensure both ignore entries before any worktree add.
-    ensure_gitignored(plastic_home, ".worktrees/", runner: runner)
-
     # The durable lock files live inside intent dirs under the store git repo
-    # (intent 108, D2): transient state, never committed.
+    # (intent 108, D2): transient state, never committed. Unrelated to store
+    # worktrees (retired by intent 178); this stays regardless.
     ensure_gitignored(plastic_home, "*.lock", runner: runner)
 
-    # Store worktree: created against the plastic home git repo. Fail-open if the
-    # store repo is not a git repo (a fresh global store may be ungit'd).
-    store_ok = add_worktree(runner, repo: plastic_home,
-                            worktree: p["store"], branch: p["store_branch"],
-                            label: "store")
-
     # Code worktree: MANDATORY for project intents. Fail-open when the repo is
     # unresolvable or non-git -- that is the global-store-only / non-git case.
     repo = repo_for(slug, home: home)
@@ -173,9 +162,6 @@ module Worktree
            "is unresolvable or not a git repo; code worktree skipped"
     end
 
-    block["store"] = store_ok ? p["store"] : nil
-    block["store_branch"] = store_ok ? p["store_branch"] : nil
-
     # provisioned is true only when the MANDATORY code worktree exists. The gate
     # fails open on provisioned: false (non-git / global-only).
     block["provisioned"] = code_ok
@@ -184,26 +170,22 @@ module Worktree
     bridge_data
   end
 
-  # Remove both worktrees (then `git worktree prune`), clear the worktree block.
+  # Remove the worktree (then `git worktree prune`), clear the worktree block.
   # No-op when nothing was provisioned. CLEANUP (73c3) layers the merge-vs-remove
   # policy on top via `finish`; this is the plain remove. Pass `remove: false` to
   # clear the block WITHOUT touching git (so `finish` can merge first, then call
-  # release to drop the worktrees once the code branch is integrated).
+  # release to drop the worktree once the code branch is integrated).
   def release(bridge_data, home: Dir.home, runner: ShellRunner.new, remove: true)
     return bridge_data unless bridge_data.is_a?(Hash)
     block = bridge_data["worktree"]
     return bridge_data unless block.is_a?(Hash)
 
     if remove
-      plastic_home = File.expand_path(File.join(home, ".plastic"))
       slug = slug_for_store(bridge_data.dig("intent", "store").to_s, home: home)
       repo = repo_for(slug, home: home)
 
       remove_worktree(runner, repo: repo, worktree: block["code"]) if repo && block["code"]
-      remove_worktree(runner, repo: plastic_home, worktree: block["store"]) if block["store"]
-
       prune(runner, repo: repo) if repo
-      prune(runner, repo: plastic_home)
     end
 
     bridge_data.delete("worktree")
@@ -212,7 +194,7 @@ module Worktree
 
   # --- cleanup policy (merge-vs-remove) -------------------------------------
 
-  # Finish an intent's delivery by tearing down its worktrees, optionally merging
+  # Finish an intent's delivery by tearing down its worktree, optionally merging
   # the code branch back first (intent 73c3). The merge-vs-remove decision is the
   # one piece of policy on top of the plain `release`:
   #

package/scripts/lib/worktree_sweep.rb

@@ -0,0 +1,129 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "worktree"
+require_relative "bridge"
+
+# WorktreeSweep -- the one-time orphan sweep for store worktrees retired by
+# intent 178 (D2). Pure candidate classification plus a thin apply step, both
+# dependency-injected (a ShellRunner, an explicit plastic_home) so the whole
+# module is hermetically testable: no call here ever falls back to the real
+# `Dir.home` (the intent 169 hermeticity lesson applies here too).
+#
+# A candidate is REMOVE iff its intent is terminal (Completed or Abandoned in
+# SOME store's INDEX.md) AND its branch carries no commits ahead of that
+# store's main. Any ambiguity -- no matching intent directory found in any
+# store, an unreadable INDEX, or a branch that cannot be resolved -- SPARES
+# the candidate rather than removing it. This module never shells out for
+# `worktree remove`; that only happens in `apply!`, and only for candidates
+# already marked REMOVE.
+module WorktreeSweep
+  module_function
+
+  Candidate = Struct.new(:name, :dir, :branch, :intent_dir, :status, :ahead_count,
+                         :decision, :reason, keyword_init: true)
+
+  TERMINAL_STATUSES = %w[Completed Abandoned].freeze
+
+  # All worktree dirs under `<plastic_home>/.worktrees/`, classified. `runner`
+  # is injected (default a real ShellRunner) so tests never shell out.
+  def candidates(plastic_home:, runner: Worktree::ShellRunner.new)
+    Dir.glob(File.join(plastic_home, ".worktrees", "*"))
+       .select { |d| File.directory?(d) }
+       .sort
+       .map { |dir| classify(dir, plastic_home: plastic_home, runner: runner) }
+  end
+
+  def classify(dir, plastic_home:, runner:)
+    name = File.basename(dir)
+    branch = "plastic-store/#{name}"
+    intent_dir = resolve_intent_dir(plastic_home, name)
+    status = intent_dir ? index_status(intent_dir, name) : nil
+    ahead = intent_dir ? branch_ahead_count(runner, plastic_home, branch) : nil
+
+    terminal = TERMINAL_STATUSES.include?(status)
+    ahead_or_unknown = ahead.nil? || ahead > 0
+    decision = (terminal && !ahead_or_unknown) ? :remove : :spare
+
+    Candidate.new(name: name, dir: dir, branch: branch, intent_dir: intent_dir,
+                  status: status, ahead_count: ahead, decision: decision,
+                  reason: reason_for(intent_dir, status, ahead, terminal))
+  end
+
+  # The FIRST real intent directory literally named `{id}--{slug}` (the exact
+  # worktree dir name) found under the global store or any project store.
+  # Matching on the full name, not just the numeric id, sidesteps id
+  # collisions across projects (ids are only unique WITHIN one store).
+  def resolve_intent_dir(plastic_home, name)
+    candidates = [File.join(plastic_home, "store", name)] +
+                 Dir.glob(File.join(plastic_home, "projects", "*", "store", name))
+    candidates.find { |d| Dir.exist?(d) }
+  end
+
+  # The INDEX.md section heading (e.g. "Active", "Completed") that lists this
+  # intent dir, or nil if no INDEX.md entry links to it. Reuses
+  # Bridge.index_entry_match so this never drifts from the shared parser.
+  def index_status(intent_dir, name)
+    store = File.dirname(intent_dir)
+    index = File.join(File.dirname(store), "INDEX.md")
+    return nil unless File.exist?(index)
+
+    section = nil
+    File.foreach(index) do |line|
+      stripped = line.chomp
+      if stripped.start_with?("## ")
+        section = stripped.sub(/\A##\s*/, "").strip
+        next
+      end
+      m = Bridge.index_entry_match(stripped)
+      next unless m
+      return section if m[3].to_s.include?(name)
+    end
+    nil
+  end
+
+  # Commits reachable from `branch` but not from the repo's own current
+  # (default) branch, or nil if either cannot be resolved. nil is treated as
+  # "ahead or unknown" by `classify` (fail SPARE, never fail REMOVE).
+  def branch_ahead_count(runner, plastic_home, branch)
+    target = Worktree.current_branch(runner, repo: plastic_home)
+    return nil if target.nil? || target == branch
+    res = runner.run("-C", plastic_home, "rev-list", "--count", "#{target}..#{branch}")
+    return nil unless res.success?
+    res.stdout.to_s.strip.to_i
+  end
+
+  def reason_for(intent_dir, status, ahead, terminal)
+    return "no matching intent directory found in any store (orphaned/ambiguous reference)" unless intent_dir
+    return "ahead of main by #{ahead} commit(s); sparing to avoid stranding unmerged work" if ahead.nil? || ahead > 0
+    return "intent status is #{status.inspect}, not terminal; sparing" unless terminal
+    "terminal (#{status}) and not ahead of main"
+  end
+
+  # A stable, human-reviewable dry-run report. Every candidate is listed,
+  # remove and spare alike, with its full reasoning -- this is the artifact
+  # the owner reviews BEFORE anything is deleted (D2, AC5).
+  def dry_run_report(candidates, now: Time.now)
+    lines = ["Store-worktree sweep dry run -- #{now.utc.iso8601}", ""]
+    candidates.each do |c|
+      tag = c.decision == :remove ? "REMOVE" : "SPARE "
+      lines << "#{tag}  #{c.name}  status=#{c.status.inspect}  ahead=#{c.ahead_count.inspect}  #{c.reason}"
+    end
+    remove_n = candidates.count { |c| c.decision == :remove }
+    lines << ""
+    lines << "#{remove_n} of #{candidates.length} candidate(s) eligible for removal. " \
+             "Nothing has been removed yet; re-run with --apply after review."
+    lines.join("\n")
+  end
+
+  # Removes only :remove-decision candidates, via `git worktree remove` (falls
+  # back to --force only inside Worktree.remove_worktree's own existing
+  # retry), then `git worktree prune` once at the end. Returns the list of
+  # candidates actually removed. Never called for a :spare candidate.
+  def apply!(candidates, plastic_home:, runner: Worktree::ShellRunner.new)
+    removed = candidates.select { |c| c.decision == :remove }
+    removed.each { |c| Worktree.remove_worktree(runner, repo: plastic_home, worktree: c.dir) }
+    Worktree.prune(runner, repo: plastic_home) unless removed.empty?
+    removed
+  end
+end

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__