@zalom/plastic 1.4.1 → 1.6.0

package/scripts/lib/installer_core.rb

@@ -330,6 +330,11 @@ class InstallerCore
       "scripts/rebuild-graph" => "scripts/rebuild-graph",
       "scripts/lib/restore_intent_v1.rb" => "scripts/lib/restore_intent_v1.rb",
       "scripts/restore-intent-v1" => "scripts/restore-intent-v1",
+"scripts/lib/revisions_writer.rb" => "scripts/lib/revisions_writer.rb",
+"scripts/maintenance-run" => "scripts/maintenance-run",
+"scripts/lib/maintenance_git.rb" => "scripts/lib/maintenance_git.rb",
+"scripts/lib/worktree_sweep.rb" => "scripts/lib/worktree_sweep.rb",
+"scripts/sweep-store-worktrees" => "scripts/sweep-store-worktrees",
       "scripts/validate-intent" => "scripts/validate-intent",
       "scripts/new-intent" => "scripts/new-intent",
       "scripts/end-intent" => "scripts/end-intent",
@@ -608,8 +613,8 @@ class InstallerCore
   end
 
   # Render one repo agents/*.md into a deterministic Codex agent TOML document. Fixed field
-  # order (name, description, one model field, developer_instructions) so regenerate is
-  # byte-identical (idempotency).
+  # order (name, description, the model field(s) from codex_model_fields, developer_instructions)
+  # so regenerate is byte-identical (idempotency).
   def render_codex_agent_toml(source_path, override)
     front, body = split_frontmatter(File.read(source_path))
     name = (front["name"] || File.basename(source_path, ".md")).to_s
@@ -636,14 +641,21 @@ class InstallerCore
     end
   end
 
-  # The single model-selection line. A known tier alias (opus/sonnet/haiku) emits
-  # model_reasoning_effort only; any other non-empty value is a literal Codex model id
-  # emitted verbatim as `model`. Empty -> no line (the agent inherits the session default).
+  # The model-selection line(s). A known tier alias (opus/sonnet/haiku) emits BOTH a `model` line
+  # (from AgentModels.codex_model_for, the intent-186 per-role Codex identity) and a
+  # model_reasoning_effort line, model first for deterministic byte-identical regenerate. Any other
+  # non-empty value is a literal Codex model id emitted verbatim as `model` only. Empty -> no line
+  # (the agent inherits the session default). If an alias somehow lacks a mapped model, the effort
+  # line still emits alone (backward-safe).
   def codex_model_fields(effective)
     return "" if effective.nil? || effective.to_s.empty?
     effort = AgentModels.effort_for(effective)
     if effort
-      %(model_reasoning_effort = "#{effort}")
+      lines = []
+      model = AgentModels.codex_model_for(effective)
+      lines << %(model = "#{toml_inline_escape(model)}") if model && !model.to_s.empty?
+      lines << %(model_reasoning_effort = "#{effort}")
+      lines.join("\n")
     else
       %(model = "#{toml_inline_escape(effective.to_s)}")
     end

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