@zalom/plastic 1.14.0 → 2.0.0-alpha.1

package/scripts/install.rb

@@ -3,7 +3,11 @@
 # frozen_string_literal: true
 
 # Plastic — `install` verb. Runs via `npx @zalom/plastic install` (bin/plastic.js) or directly.
-# Usage: ruby scripts/install.rb [--claude|--codex|--hermes|--all] [--alpha|--beta|--latest] [--reinstall] [--force] [--help]
+# Usage: ruby scripts/install.rb [--claude|--codex|--hermes|--all] [--reinstall] [--force] [--help]
+#
+# The package version selects the channel: `npx @zalom/plastic@alpha install --claude` (or
+# a pinned `@2.0.0-alpha.1`). The channel flags this verb once listed never selected a
+# package and were removed in 2.0 (intent 310).
 #
 # One-shot by design:
 #   - no install present  -> fresh install + bootstrap store
@@ -206,7 +210,7 @@ class Install < InstallerCore
     return if codex_like.none? { |a| installed.any? { |r| r[:agent] == a[:name] } }
 
     puts "   Codex: open Codex, run /hooks, and trust the Plastic hook definitions."
-    puts "   Plastic's gates will not fire until you do.\n\n"
+    puts "   Plastic's hooks will not fire until you do.\n\n"
   end
 
   def show_help
@@ -223,10 +227,8 @@ class Install < InstallerCore
         --hermes      Install for Hermes
         --all         Install for all supported agents
 
-      Channel options:
-        --latest      Stable channel (default)
-        --beta        Beta channel
-        --alpha       Alpha channel
+      Channel: pin the package, e.g. `npx @zalom/plastic@alpha install --claude`
+        (@latest is stable and the default; @beta and @alpha are the other channels)
 
       Other options:
         --reinstall          Re-sync core files for the installed version (repair). Store untouched.

package/scripts/lib/agent_models.rb

@@ -12,13 +12,7 @@ module AgentModels
   # file basenames without the `.md` extension.
   TIER_DEFAULTS = {
     "plastic-enforcer" => "opus",
-    "plastic-brainstorming" => "opus",
-    "plastic-planner" => "opus",
-    "plastic-spec-specialist" => "sonnet",
-    "plastic-executor" => "sonnet",
-    "plastic-intent-curator" => "sonnet",
-    "plastic-future-intent-researcher" => "sonnet",
-    "plastic-intent-discovery" => "sonnet"
+    "plastic-executor" => "sonnet"
   }.freeze
 
   # The two advisor agents (intent 185 final design): plastic-advisor (the real

package/scripts/lib/arm.rb

@@ -0,0 +1,283 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require_relative "lock"
+require_relative "worktree"
+require_relative "session_ledger"
+require_relative "savepoint"
+
+# Arm - how an auto team takes an intent and gives it back (intent 307).
+#
+# Three durable facts make a delivery: the delivery lock in the intent
+# directory (who owns it), the code worktree under the project repo (where
+# the code lands), and the per-session pointer in the global store's `.tmp/`
+# (which intent this session records into; a day id means the day ledger).
+# Before 2.0 a fourth thing, a `/tmp` bridge JSON, cached all three plus a
+# stage snapshot; ruling 6 of intent 296 retired it, and this module is what
+# replaced the bridge's arm, disarm, and repair methods (removed in 2.0, intent 307).
+#
+# Pure and dependency-injected: every path and clock is an argument, every git
+# call goes through an injected runner, and the only environment read is the
+# `env:` value the caller passes to `resolve_session`. Nothing here raises for
+# a lock outcome; callers get a status and decide.
+module Arm
+  module_function
+
+  STATUSES = %i[acquired owned held stale excluded corrupt].freeze
+
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+
+  # Deterministic, session-less key derived from the store and the intent id,
+  # for headless runs that carry no session id at all (moved from Bridge).
+  def derive_key(store, intent_id)
+    "auto-" + Digest::SHA256.hexdigest("#{store}/#{intent_id}")[0, 10]
+  end
+
+  # The session that keys a lock: the explicit id, else the env id the caller
+  # read (CLAUDE_CODE_SESSION_ID), else the derived key. Never nil.
+  def resolve_session(explicit, env: nil, store:, intent_id:)
+    return explicit.to_s.strip unless blank?(explicit)
+    return env.to_s.strip unless blank?(env)
+    derive_key(store, intent_id)
+  end
+
+  # --- derivations (no I/O beyond Dir.exist?) ---------------------------------
+
+  def intent_id_for(intent_dir)
+    File.basename(intent_dir.to_s).split("--", 2).first
+  end
+
+  def store_for(intent_dir)
+    File.dirname(File.expand_path(intent_dir))
+  end
+
+  # The home (parent of `.plastic`) an intent dir belongs to, else the given
+  # fallback. A sandboxed store never resolves to the real Dir.home.
+  def home_for(intent_dir, home: Dir.home)
+    Worktree.home_from_store(store_for(intent_dir)) || home
+  end
+
+  def global_store(home)
+    File.join(File.expand_path(home), ".plastic", "store")
+  end
+
+  # The minimal hash Worktree.provision, release, and finish consume: the
+  # intent block plus, when asked, the derived worktree block.
+  def bridge_hash(intent_dir:, home: Dir.home, with_worktree: true)
+    dir = File.expand_path(intent_dir)
+    data = {
+      "intent" => { "id" => intent_id_for(dir), "dir" => File.basename(dir), "store" => store_for(dir) },
+    }
+    data["worktree"] = worktree_block(intent_dir: dir, home: home) if with_worktree
+    data
+  end
+
+  # `{code, code_branch, provisioned}` derived from projects.yml and the
+  # intent id: the same path provision creates, `provisioned` iff it exists.
+  def worktree_block(intent_dir:, home: Dir.home)
+    dir = File.expand_path(intent_dir)
+    store = store_for(dir)
+    h = home_for(dir, home: home)
+    slug = Worktree.slug_for_store(store, home: h)
+    p = Worktree.paths(slug: slug, intent_id: intent_id_for(dir),
+                       intent_slug: Worktree.slug_from_dir(dir), home: h)
+    code = p["code"]
+    provisioned = !blank?(code) && Dir.exist?(code)
+    {
+      "code" => provisioned ? code : nil,
+      "code_branch" => provisioned ? p["code_branch"] : nil,
+      "provisioned" => provisioned,
+    }
+  end
+
+  # --- the pointer -------------------------------------------------------------
+
+  def pointer_path(session, home:)
+    store = global_store(home)
+    SessionLedger.pointer_path(store, SessionLedger.short_session_id(nil, session))
+  end
+
+  def read_pointer(session, home:)
+    path = pointer_path(session, home: home)
+    File.exist?(path) ? File.read(path).strip : nil
+  end
+
+  def write_pointer(session, value, home:)
+    store = global_store(home)
+    SessionLedger.ensure_tmp_root(store)
+    path = pointer_path(session, home: home)
+    FileUtils.mkdir_p(File.dirname(path))
+    File.write(path, "#{value}\n")
+    path
+  end
+
+  # --- arm ---------------------------------------------------------------------
+
+  # Take an intent for `session`: acquire delivery.lock (stamped with the run
+  # mode and the provenance the caller knows), provision the code worktree
+  # (fail-open for a global-only or non-git intent), and point the session at
+  # the intent. Returns `{status:, lock:, worktree:, session:, pointer:}`.
+  # A held, stale, excluded, or corrupt lock returns that status with the
+  # lock data read and touches nothing.
+  def arm(intent_dir:, session:, mode: "auto", home: Dir.home, harness: nil,
+          agent: nil, model: nil, thread: nil, now: Time.now, runner: Worktree::ShellRunner.new,
+          host: Socket.gethostname)
+    raise ArgumentError, "mode must be auto or guided" unless %w[auto guided].include?(mode.to_s)
+    dir = File.expand_path(intent_dir)
+    key = resolve_session(session, store: store_for(dir), intent_id: intent_id_for(dir))
+    h = home_for(dir, home: home)
+
+    status, lock = Lock.acquire(dir, session: key, host: host, now: now,
+                                harness: harness, agent: agent, model: model,
+                                thread: thread, run_mode: mode.to_s)
+    unless %i[acquired owned].include?(status)
+      return { status: status, lock: lock, worktree: nil, session: key, pointer: nil }
+    end
+
+    data = bridge_hash(intent_dir: dir, home: h, with_worktree: false)
+    begin
+      Worktree.provision(data, home: h, runner: runner)
+    rescue StandardError => e
+      warn "plastic: worktree provision raised, continuing unprovisioned: #{e.message}"
+    end
+
+    # The pointer is what the capture and record hooks read; they key on the
+    # harness's real session id, so a derived key gets no pointer (nothing would
+    # ever read it). A pointer failure warns and never undoes an acquired lock.
+    pointer = nil
+    unless key == derive_key(store_for(dir), intent_id_for(dir))
+      begin
+        pointer = write_pointer(key, intent_id_for(dir), home: h)
+      rescue StandardError => e
+        warn "plastic: session pointer not written (#{e.message}); the lock is held regardless"
+      end
+    end
+    { status: status, lock: lock, worktree: worktree_block(intent_dir: dir, home: h),
+      session: key, pointer: pointer }
+  end
+
+  # --- disarm ------------------------------------------------------------------
+
+  # Give the intent back: remove the worktree (when `remove`), release the
+  # lock as its recorded owner (falling back to `session`), and reset the
+  # session pointer to today's day id when it named this intent. Returns
+  # the lock release status (:released, :none, :not_owner, or :raised).
+  def disarm(intent_dir:, session:, home: Dir.home, runner: Worktree::ShellRunner.new,
+             remove: true, now: Time.now)
+    dir = File.expand_path(intent_dir)
+    h = home_for(dir, home: home)
+    key = resolve_session(session, store: store_for(dir), intent_id: intent_id_for(dir))
+
+    begin
+      Worktree.release(bridge_hash(intent_dir: dir, home: h), home: h, runner: runner, remove: remove)
+    rescue StandardError => e
+      warn "plastic: worktree release raised, continuing: #{e.message}"
+    end
+
+    lock = Lock.read(dir)
+    owner = lock && !blank?(lock["owner_session"]) ? lock["owner_session"] : key
+    release_status = begin
+      Lock.release(dir, session: owner)
+    rescue StandardError => e
+      warn "plastic: delivery lock release raised for #{dir}, continuing: #{e.message}"
+      :raised
+    end
+
+    begin
+      reset_pointer(key, intent_id_for(dir), home: h, now: now)
+    rescue StandardError => e
+      warn "plastic: session pointer not reset (#{e.message})"
+    end
+    release_status
+  end
+
+  # Point the session back at the day ledger, but only when it names `intent_id`.
+  def reset_pointer(session, intent_id, home:, now: Time.now)
+    current = read_pointer(session, home: home)
+    return false unless current == intent_id.to_s
+    write_pointer(session, SessionLedger.day_id(now), home: home)
+    true
+  end
+
+  # --- repair ------------------------------------------------------------------
+
+  # One idempotent repair (the lock half of the bridge's repair, removed in 2.0):
+  # remove a corrupt lock, back off from a fresh foreign lock (`held`), report
+  # a stale foreign lock (`stale`) for the explicit reclaim verb, keep and
+  # enrich an own lock, heartbeat a delegated one, acquire when none, and
+  # provision the worktree so the repaired intent has its checkout.
+  def repair(intent_dir:, session:, home: Dir.home, now: Time.now, harness: nil,
+             agent: nil, model: nil, thread: nil, run_mode: nil, hint_harness: nil,
+             runner: Worktree::ShellRunner.new)
+    dir = File.expand_path(intent_dir)
+    h = home_for(dir, home: home)
+    key = resolve_session(session, store: store_for(dir), intent_id: intent_id_for(dir))
+    actions = []
+
+    if Lock.corrupt?(dir)
+      File.delete(Lock.path(dir))
+      actions << "removed corrupt delivery.lock"
+    end
+
+    lock = Lock.read(dir)
+    if lock && !Lock.authorized?(lock, key)
+      if Lock.fresh?(dir, now: now)
+        return { "status" => "held", "owner" => lock["owner_session"],
+                 "actions" => actions, "session" => key }
+      end
+      return { "status" => "stale", "owner" => lock["owner_session"],
+               "actions" => actions, "session" => key,
+               "hint" => "run #{Lock.skill_ref('plastic-doctor', harness: hint_harness || harness)} " \
+                         "reclaim the lock to take over with an audit" }
+    end
+
+    mode = blank?(run_mode) ? (lock && lock["run_mode"]) : run_mode.to_s
+    if lock
+      if lock["owner_session"].to_s == key.to_s
+        lock_data = lock.dup
+        { "owner_harness" => harness, "owner_agent" => agent, "owner_model" => model,
+          "owner_thread" => thread, "run_mode" => mode }.each do |field, value|
+          lock_data[field] = value.to_s unless blank?(value)
+        end
+        Lock.write(dir, lock_data)
+        Lock.heartbeat(dir, session: key, now: now)
+      else
+        Lock.heartbeat(dir, session: key, now: now)
+        lock_data = Lock.read(dir)
+      end
+      role = lock_data["owner_session"].to_s == key.to_s ? "owner" : "delegate"
+      actions << "lock kept (#{role})"
+    else
+      status, lock_data = Lock.acquire(dir, session: key, now: now, harness: harness,
+                                       agent: agent, model: model, thread: thread,
+                                       run_mode: mode)
+      actions << "lock #{status}"
+    end
+
+    begin
+      Worktree.provision(bridge_hash(intent_dir: dir, home: h, with_worktree: false), home: h, runner: runner)
+    rescue StandardError => e
+      warn "plastic: worktree provision raised during repair, continuing unprovisioned: #{e.message}"
+    end
+    actions << "worktree #{worktree_block(intent_dir: dir, home: h)['provisioned'] ? 'present' : 'absent'}"
+    actions << "stage #{Savepoint.derive_stage(dir)}"
+
+    { "status" => "repaired", "actions" => actions, "lock" => lock_data, "session" => key }
+  end
+
+  # The intent directory this session's pointer names, searched in the given
+  # stores in order; nil when the pointer is absent, empty, or a day id.
+  def intent_dir_from_pointer(session, home:, stores:)
+    current = read_pointer(session, home: home)
+    return nil if blank?(current) || SessionLedger.valid_day_id?(current)
+    stores.each do |store|
+      match = Dir.glob(File.join(store, "#{current}--*")).find { |p| File.directory?(p) }
+      return match if match
+    end
+    nil
+  end
+end

package/scripts/lib/backfill_intent.rb

@@ -0,0 +1,316 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+require_relative "scaffold_intent"
+require_relative "savepoint"
+require_relative "intent_validator"
+require_relative "worktree"
+
+# BackfillIntent (intent 308) - write the four judgment documents of an intent from its
+# record at intent end. The record is what an intent already carries by the time it
+# closes: the intent file (`## Intent`, `### Decisions`, `## Insights`), checklist.md,
+# and the diff on its own code worktree. Every section written here is a verbatim copy
+# or a mechanical rendering of one of those; a section with no source keeps the
+# template's own stub text, so nothing here invents prose. The one value that comes from
+# the caller is outcome.md's `disposition:`, the closer's explicit assertion (spec D11).
+#
+# A target is backfilled only when it is missing or still the scaffold placeholder: the
+# first line is the sentinel AND the body under it is nothing but the template
+# (`edited_sentinel?`). A sentinel over hand-written lines counts as real. actions/ is
+# backfilled as ACTION_1.md only when `Savepoint.has_real_action?` is false. A real file
+# is never touched and there is no force flag. Every written file carries a marker
+# comment on the line after its title, never the sentinel, so every reader treats it as
+# real. A zero-byte spec.md or plan.md reads as real here exactly as it does in
+# `Savepoint.stage_file_present?` (spec D1), so the doctor surfaces never disagree.
+#
+# Pure and dependency-injected like ScaffoldIntent: never exits, never reads ARGV or ENV
+# (only the ambient Dir.home default), and takes the git seam as `runner:` so tests drive
+# it in process with a fake runner.
+module BackfillIntent
+  module_function
+
+  TARGETS = ["spec.md", "plan.md", "actions/ACTION_1.md", "outcome.md"].freeze
+  TEMPLATED = ["spec.md", "plan.md", "outcome.md"].freeze
+  MARKER_PREFIX = "<!-- backfilled from the record by end-intent on "
+  ITEM_RE = /\A\s*- \[( |x|X)\] /.freeze
+  TITLE_RE = /\A# /.freeze
+  STUB_SECTIONS = {
+    "## Goals" => "- ...\n", "## Non-Goals" => "- ...\n",
+    "## Approach" => "(the chosen approach, in prose)\n",
+    "## Alternatives Considered" => "- <alternative>: not chosen because ...\n",
+  }.freeze
+
+  def marker(now)
+    "#{MARKER_PREFIX}#{now.utc.iso8601} -->"
+  end
+
+  # --- templates ---------------------------------------------------------------------
+
+  # { "spec.md" => text, ... } for the templates that exist, else {}.
+  def load_templates(templates_dir: nil, home: Dir.home)
+    dir = templates_dir || ScaffoldIntent.resolve_templates_dir(home: home)
+    return {} if dir.nil?
+
+    TEMPLATED.each_with_object({}) do |name, acc|
+      path = File.join(dir, name)
+      acc[name] = File.read(path) if File.exist?(path)
+    end
+  end
+
+  # --- target selection --------------------------------------------------------------
+
+  # True iff `path` starts with the sentinel and its body carries a non-blank, non-title
+  # line that the template for this file does not: someone wrote under the sentinel.
+  # With no template known, any body line at all means edited.
+  def edited_sentinel?(path, template_text, known_lines: [])
+    lines = File.read(path).lines
+    return false unless lines.first.to_s.chomp == Savepoint::PLACEHOLDER_SENTINEL
+
+    body = lines.drop(1).map(&:strip).reject { |l| l.empty? || l.match?(TITLE_RE) }
+    return body.any? if template_text.nil?
+
+    known = template_text.lines.map(&:strip).reject(&:empty?) + known_lines.map(&:strip)
+    (body - known).any?
+  rescue StandardError
+    true
+  end
+
+  # { targets: [rel], edited: [rel] }: the targets that need writing, and the sentinel
+  # files that were left alone because their body was edited.
+  def classify(intent_dir, templates: {}, known_lines: [])
+    targets = []
+    edited = []
+    TEMPLATED.each do |rel|
+      path = File.join(intent_dir, rel)
+      next if Savepoint.stage_file_present?(path)
+
+      if File.exist?(path) && edited_sentinel?(path, templates[rel], known_lines: known_lines)
+        edited << rel
+      else
+        targets << rel
+      end
+    end
+    unless Savepoint.has_real_action?(intent_dir)
+      action = File.join(intent_dir, "actions", "ACTION_1.md")
+      if File.exist?(action) && !Savepoint.stage_file_present?(action) && edited_sentinel?(action, nil)
+        edited << "actions/ACTION_1.md"
+      elsif !File.exist?(action) || !Savepoint.stage_file_present?(action)
+        targets << "actions/ACTION_1.md"
+      end
+    end
+    { targets: TARGETS & targets, edited: TARGETS & edited }
+  end
+
+  def targets_for(intent_dir, templates_dir: nil, home: Dir.home)
+    classify(intent_dir, templates: load_templates(templates_dir: templates_dir, home: home))[:targets]
+  end
+
+  # --- reading the record (pure over file contents) ---------------------------------
+
+  def strip_edges(lines)
+    ScaffoldIntent.strip_blank_edges(lines)
+  end
+
+  def section_lines(text, heading)
+    body = ScaffoldIntent.sections_from(text)[heading]
+    return [] if body.nil?
+
+    strip_edges(body.lines.map(&:rstrip)).reject { |l| l.start_with?("<!--") && l.end_with?("-->") }
+  end
+
+  # Every GFM checkbox item of checklist.md with its section and done flag. A continuation
+  # line (indented, not an item, not a heading, not a table row) stays attached to the item
+  # above it so a wrapped item round-trips verbatim.
+  def checklist_items(text)
+    items = []
+    section = nil
+    text.each_line do |raw|
+      line = raw.rstrip
+      if line.start_with?("## ")
+        section = line
+      elsif (m = ITEM_RE.match(line))
+        items << { line: line, done: m[1] != " ", section: section }
+      elsif items.any? && line.start_with?("  ") && !line.start_with?("  |") && section == items.last[:section]
+        items.last[:line] = "#{items.last[:line]}\n#{line}"
+      end
+    end
+    items
+  end
+
+  def session_log_lines(text)
+    section_lines(text, "## Session Log").select { |l| l.start_with?("|") }
+  end
+
+  # [record, nil] or [nil, message] when the intent file is missing. `record[:notes]`
+  # names every source that was absent; an absent source never stops the write.
+  def read_record(intent_dir)
+    intent_file = Savepoint.intent_file(intent_dir)
+    return [nil, "the intent file is missing at #{intent_file}"] unless File.exist?(intent_file)
+
+    content = File.read(intent_file)
+    fm = IntentValidator.parse_frontmatter_text(content)
+    name = fm.is_a?(Hash) ? fm["intent"].to_s.strip : ""
+    notes = []
+    if name.empty?
+      name = File.basename(intent_dir)
+      notes << "the intent file has no frontmatter intent name; the directory name stands in"
+    end
+    decisions, = ScaffoldIntent.extract_decisions(content)
+    notes << "the intent file has no ### Decisions list; spec.md says so" if decisions.nil?
+
+    checklist = File.join(intent_dir, "checklist.md")
+    checklist_text = ""
+    if Savepoint.stage_file_present?(checklist)
+      checklist_text = File.read(checklist)
+    else
+      notes << "checklist.md is missing or still a placeholder; the item sections say so"
+    end
+
+    [{
+      name: name,
+      intent_body: section_lines(content, "## Intent"),
+      decisions: decisions,
+      insights: section_lines(content, "## Insights"),
+      items: checklist_items(checklist_text),
+      session_log: session_log_lines(checklist_text),
+      notes: notes,
+    }, nil]
+  end
+
+  # --- rendering (pure) ---------------------------------------------------------------
+
+  def block(lines, empty)
+    lines.empty? ? "#{empty}\n" : "#{lines.join("\n")}\n"
+  end
+
+  def template_stub(template_text, heading)
+    body = template_text && ScaffoldIntent.sections_from(template_text)[heading]
+    body = STUB_SECTIONS.fetch(heading, "") if body.nil? || body.strip.empty?
+    "#{body.rstrip}\n"
+  end
+
+  def render(record, disposition:, summary:, verification:, now:, templates: {})
+    mark = marker(now)
+    items = record[:items].map { |i| i[:line] }
+    done = record[:items].select { |i| i[:done] }.map { |i| i[:line] }
+    open = record[:items].reject { |i| i[:done] }.map { |i| i[:line] }
+    decisions = record[:decisions].nil? ? "(none recorded in the intent file)\n" : record[:decisions]
+    decisions += "\n" unless decisions.end_with?("\n")
+
+    spec = +"# Spec: #{record[:name]}\n#{mark}\n\n"
+    spec << "## Problem\n#{block(record[:intent_body], '(not recorded in the intent file)')}\n"
+    STUB_SECTIONS.each_key { |h| spec << "#{h}\n#{template_stub(templates['spec.md'], h)}\n" }
+    spec << "## Decisions\n#{decisions}\n"
+    spec << "## Acceptance Criteria\n#{block(items, '(no checklist items recorded)')}\n"
+    spec << "## Open Questions\nNone\n"
+
+    plan = +"# Plan: #{record[:name]}\n#{mark}\n\n"
+    plan << "## Goal\n#{record[:name]}\n\n"
+    plan << "## Steps\n#{block(items, '(no checklist items recorded)')}\n"
+    plan << "## Notes\n#{block(record[:insights], '(no insights recorded)')}"
+
+    action = +"# ACTION_1: #{record[:name]}\n#{mark}\n\n"
+    action << "## Items\n#{block(items, '(no checklist items recorded)')}\n"
+    action << "## Session Log\n#{block(record[:session_log], '(none)')}"
+
+    summary_text = summary.to_s.strip
+    summary_text = "(no summary given at close)" if summary_text.empty?
+    outcome = +"---\ndisposition: #{disposition}\n---\n# Outcome: #{record[:name]}\n#{mark}\n\n"
+    outcome << "## Summary\n#{summary_text}\n\n"
+    outcome << "## Delivered\n#{block(done, '(no completed checklist items recorded)')}\n"
+    outcome << "## Verification\n#{verification.to_s.strip.empty? ? "(no diff available)\n" : verification}\n"
+    outcome << "## Follow-ups\n#{block(open, 'None')}"
+
+    { "spec.md" => spec, "plan.md" => plan, "actions/ACTION_1.md" => action, "outcome.md" => outcome }
+  end
+
+  # --- the diff, from this intent's own code worktree only -----------------------------
+
+  # The provisioned code worktree for this intent when it exists on disk, else nil. Never
+  # the current directory's repo: a store-only intent closed from an unrelated checkout
+  # must not report that checkout's diff.
+  def worktree_dir(store:, id:, intent_dir:, home: Dir.home)
+    wt_home = Worktree.home_from_store(store) || home
+    slug = Worktree.slug_for_store(store, home: wt_home)
+    return nil if slug.nil?
+
+    intent_slug = File.basename(intent_dir).split("--", 2).last
+    code = Worktree.paths(slug: slug, intent_id: id, intent_slug: intent_slug, home: wt_home)["code"]
+    code && Dir.exist?(code) ? code : nil
+  end
+
+  def verification_body(store:, id:, intent_dir:, home:, runner:)
+    repo = worktree_dir(store: store, id: id, intent_dir: intent_dir, home: home)
+    return "Diffstat unavailable: this intent provisioned no code worktree\n" if repo.nil?
+
+    base = ScaffoldIntent.detect_base_branch(repo, runner: runner)
+    return "Diffstat unavailable: no base branch could be detected (no origin/HEAD, main, or master)\n" if base.nil?
+
+    stat, err = ScaffoldIntent.diffstat(repo, base, runner: runner)
+    return "Diffstat unavailable: #{err}\n" if stat.nil?
+
+    "Diffstat against #{base}:\n```\n#{stat}#{stat.end_with?("\n") ? "" : "\n"}```\n"
+  rescue StandardError => e
+    "Diffstat unavailable: #{e.message}\n"
+  end
+
+  # --- writing, atomic inside the intent dir -------------------------------------------
+
+  def write_atomic(intent_dir, relative, content)
+    target = File.join(intent_dir, relative)
+    FileUtils.mkdir_p(File.dirname(target))
+    tmp = File.join(File.dirname(target), ".filing-#{File.basename(target)}")
+    File.write(tmp, content)
+    File.rename(tmp, target)
+    target
+  end
+
+  # A `.filing-*` left by an earlier crash would otherwise ride into the store commit.
+  def remove_stale_filing(intent_dir)
+    Dir.glob([File.join(intent_dir, ".filing-*"), File.join(intent_dir, "actions", ".filing-*")]).each do |f|
+      File.delete(f) if File.file?(f)
+    end
+  end
+
+  # Returns { written: [rel], skipped: [rel], notes: [String] }. `skipped` lists the
+  # targets that already carry real content (an edited sentinel among them, named in
+  # `notes`). `notes` names every absent source; an absent source never stops the write.
+  # One savepoint line, `Exec  backfilled <list>`, records the fact (idempotent per list).
+  def run(intent_dir:, store:, id:, disposition:, summary: nil, home: Dir.home,
+          runner: Worktree::ShellRunner.new, templates_dir: nil, now: Time.now)
+    result = { written: [], skipped: [], notes: [] }
+    remove_stale_filing(intent_dir)
+
+    templates = load_templates(templates_dir: templates_dir, home: home)
+    record, err = read_record(intent_dir)
+    if record.nil?
+      result[:notes] << err
+      result[:skipped] = TARGETS - classify(intent_dir, templates: templates)[:targets]
+      return result
+    end
+
+    classified = classify(intent_dir, templates: templates, known_lines: [record[:name]])
+    targets = classified[:targets]
+    result[:skipped] = TARGETS - targets
+    classified[:edited].each do |rel|
+      result[:notes] << "#{rel} carries a sentinel over hand-written content; left untouched"
+    end
+    result[:notes].concat(record[:notes])
+    return result if targets.empty?
+
+    verification = nil
+    if targets.include?("outcome.md")
+      verification = verification_body(store: store, id: id, intent_dir: intent_dir, home: home, runner: runner)
+    end
+    docs = render(record, disposition: disposition, summary: summary, verification: verification,
+                  now: now, templates: templates)
+    targets.each do |rel|
+      write_atomic(intent_dir, rel, docs.fetch(rel))
+      result[:written] << rel
+    end
+    Savepoint.append_savepoint_line(intent_dir, "Exec", "backfilled #{result[:written].join(', ')}", now)
+    result
+  end
+end