@zalom/plastic 1.14.1 → 2.0.0-alpha.1

package/scripts/plastic-lock

@@ -2,19 +2,29 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 #
-# plastic-lock: inspect and repair the durable delivery lock (intent 108, D5),
-# and take/free per-artifact claim tokens (intent 111 D1/D5).
+# plastic-lock: take, inspect, repair, and give back the durable delivery lock
+# (intent 108, D5; intent 307), and take/free per-artifact claim tokens
+# (intent 111 D1/D5).
 #
-# Usage: plastic-lock <status|who|fix|release|reclaim|delegate|claim|release-claim>
+# Usage: plastic-lock <arm|status|who|fix|release|reclaim|delegate|claim|release-claim>
 #          [--intent-dir DIR] [--session SID] [--delegate SID] [--artifact NAME]
+#          [--harness claude|codex] [--agent NAME] [--model MODEL] [--thread ID]
+#          [--mode auto|guided] [--status finished|failed]
 #
 # Verbs:
+#   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
 #   who           compact, read-only durable owner/activity view
-#   status        report the lock file, the bridge cache, their agreement,
-#                 and any live per-artifact claims
-#   fix           idempotent repair: rebuild lock + bridge from disk truth for
-#                 the current session; never touches a fresh foreign lock
-#   release       owner clears the lock (End tail / abandoning a boarding)
+#   status        report the lock file, its freshness, the derived worktree,
+#                 whether this session's pointer names 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)
 #   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);
@@ -22,15 +32,23 @@
 #                 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 bridge.
-# Exit 0 on success/report; exit 1 when the verb is blocked (held elsewhere).
+# 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.
 
 require "json"
+require "yaml"
 require_relative "lib/bridge"
 require_relative "lib/lock"
+require_relative "lib/arm"
+require_relative "lib/session_ledger"
+
+VERBS = %w[arm status who fix release reclaim delegate claim release-claim].freeze
 
 def usage!
-  warn "usage: plastic-lock <status|who|fix|release|reclaim|delegate|claim|release-claim> " \
+  warn "usage: plastic-lock <#{VERBS.join('|')}> " \
        "[--intent-dir DIR] [--session SID] [--delegate SID] [--artifact NAME] " \
        "[--harness claude|codex] [--agent NAME] [--model MODEL] [--thread ID] " \
        "[--mode auto|guided] [--status finished|failed]"
@@ -38,7 +56,7 @@ def usage!
 end
 
 verb = ARGV.shift
-usage! unless %w[status who fix release reclaim delegate claim release-claim].include?(verb)
+usage! unless VERBS.include?(verb)
 
 opts = {}
 until ARGV.empty?
@@ -64,15 +82,29 @@ 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
 
 dir = opts[:dir]
 if dir.nil? || dir.strip.empty?
-  if verb == "who"
-    warn "plastic-lock: who is strictly durable-state only; pass --intent-dir <intent dir>"
+  if %w[who arm].include?(verb)
+    warn "plastic-lock: #{verb} needs --intent-dir <intent dir>"
     exit 1
   end
-  bridge = Bridge.discover_bridge(session: session, cwd: Dir.pwd)
-  dir = Bridge.bridge_intent_dir(bridge)
+  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>"
@@ -85,7 +117,7 @@ if verb == "who"
   basename = File.basename(dir)
   intent_id, slug = basename.split("--", 2)
   display = ->(value) { value.nil? || value.to_s.strip.empty? || value == "unknown" ? "Unknown" : value.to_s }
-  harness = ->(value) {
+  harness_name = ->(value) {
     shown = display.call(value)
     shown == "Unknown" ? shown : shown.sub(/\A./) { |char| char.upcase }
   }
@@ -99,12 +131,12 @@ if verb == "who"
 
   puts "#{intent_id} · #{slug || basename}"
   puts "State: #{view['state']}"
-  puts "Controller: #{display.call(owner['agent'])} via #{harness.call(owner['harness'])}"
+  puts "Controller: #{display.call(owner['agent'])} via #{harness_name.call(owner['harness'])}"
   puts "Session: #{display.call(view['owner_session'])}"
   puts "Heartbeat: #{view['heartbeat_at'] || 'none'}"
   puts "Claims: #{claim_text.empty? ? 'none' : claim_text.join(', ')}"
   if delegate
-    puts "Delegate: #{display.call(delegate['agent'])} via #{harness.call(delegate['harness'])}, #{display.call(delegate['status'])}"
+    puts "Delegate: #{display.call(delegate['agent'])} via #{harness_name.call(delegate['harness'])}, #{display.call(delegate['status'])}"
   else
     puts "Delegate: none"
   end
@@ -113,31 +145,59 @@ end
 
 intent_id = Bridge.intent_id_from_dir(dir)
 store = File.dirname(dir)
-name = File.basename(dir)
-key = Bridge.resolve_session(session, intent_id: intent_id, store: store)
+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}"
+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])
+  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]
+    )
+  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
+  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
+  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
+  when :corrupt
+    warn "plastic-lock: delivery.lock for intent #{intent_id} is unreadable; #{doctor_hint('fix the lock', hint_harness)}"
+    exit 1
+  end
 when "status"
   lock = Lock.read(dir)
-  bridge = Bridge.read(key, intent_id: intent_id)
+  pointer = Arm.read_pointer(key, home: home)
   report = {
     "intent_dir" => dir,
     "session" => key,
     "lock" => lock,
     "lock_fresh" => Lock.fresh?(dir),
     "lock_corrupt" => Lock.corrupt?(dir),
-    "bridge_present" => !bridge.nil?,
-    "agreement" => (lock && bridge) ?
-      (lock["owner_session"] == bridge.dig("lock", "owner_session")) : nil,
+    "worktree" => Arm.worktree_block(intent_dir: dir, home: home),
+    "pointer" => pointer,
+    "pointer_names_intent" => pointer == intent_id,
     "claims" => Claim.claims_status(dir),
   }
   puts JSON.pretty_generate(report)
 when "fix"
-  report = Bridge.repair_lock(key, intent_id: intent_id, intent_dir: dir,
-                              store: store, name: name, harness: harness,
-                              agent: opts[:agent], model: opts[:model], thread: opts[:thread],
-                              run_mode: opts[:mode],
-                              hint_harness: hint_harness)
+  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)
   puts JSON.pretty_generate(report)
   unless report["status"] == "repaired"
     warn "plastic-lock: #{report['status']} by #{report['owner']}" \
@@ -150,12 +210,7 @@ when "release"
     warn "plastic-lock: not the owner; run plastic-lock status"
     exit 1
   end
-  data = Bridge.read(key, intent_id: intent_id)
-  if data
-    data["lock"] = { "owner_session" => nil, "acquired_at" => nil,
-                     "host" => nil, "type" => nil, "delegates" => [] }
-    Bridge.write(key, data)
-  end
+  Arm.reset_pointer(key, intent_id, home: home)
   puts "released (#{result})"
 when "reclaim"
   status, lock_data = Lock.takeover(dir, session: key, harness: harness,
@@ -166,11 +221,9 @@ when "reclaim"
          "back off (no silent reclaim)"
     exit 1
   end
-  report = Bridge.repair_lock(key, intent_id: intent_id, intent_dir: dir,
-                              store: store, name: name, harness: harness,
-                              agent: opts[:agent], model: opts[:model], thread: opts[:thread],
-                              run_mode: opts[:mode],
-                              hint_harness: hint_harness)
+  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)
   puts JSON.pretty_generate(report)
 when "delegate"
   usage! if opts[:delegate].nil?

package/scripts/promote-session-item

@@ -0,0 +1,150 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# promote-session-item (intent 301): turn one session day-ledger line into a
+# registered intent through scripts/new-intent (never hand-authored), record
+# the day of origin in the new intent, and mark the line promoted.
+#
+# Usage:
+#   promote-session-item --day <YYYYMMDD> --match <substring> [--session <id>]
+#                        [--store <dir>] [--project <slug>] [--templates <dir>]
+#                        [--plastic-home <dir>] [--no-reindex]
+#
+# Target: the newest open line, else the newest pending line, whose summary
+# contains --match, tagged with --session when given, any session otherwise.
+# The intent lands in the project's store when --project names a registered
+# project, else in --store ($PLASTIC_HOME/store by default). No graph edge to
+# the day id is written (the day ledger is not a store node); the origin is
+# the `session_day:` frontmatter key plus a line under ## Context.
+#
+# Exit codes: 0 promoted (prints the intent dir last), 1 new-intent failed,
+# 2 usage error or nothing to promote.
+
+require "open3"
+require "yaml"
+require_relative "lib/session_ledger"
+require_relative "lib/session_backfill"
+require_relative "lib/store_provisioning"
+
+def usage_abort(message)
+  warn "promote-session-item: #{message}"
+  exit 2
+end
+
+def next_value!(argv, i, flag)
+  value = argv[i + 1]
+  usage_abort("#{flag} needs a value") if value.nil? || value.start_with?("--")
+  value
+end
+
+opts = { day: nil, match: nil, session: nil, store: nil, project: nil, templates: nil,
+         plastic_home: nil, reindex: true }
+i = 0
+while i < ARGV.length
+  case ARGV[i]
+  when "--day"          then opts[:day] = next_value!(ARGV, i, "--day"); i += 1
+  when "--match"        then opts[:match] = next_value!(ARGV, i, "--match"); i += 1
+  when "--session"      then opts[:session] = next_value!(ARGV, i, "--session"); i += 1
+  when "--store"        then opts[:store] = next_value!(ARGV, i, "--store"); i += 1
+  when "--project"      then opts[:project] = next_value!(ARGV, i, "--project"); i += 1
+  when "--templates"    then opts[:templates] = next_value!(ARGV, i, "--templates"); i += 1
+  when "--plastic-home" then opts[:plastic_home] = next_value!(ARGV, i, "--plastic-home"); i += 1
+  when "--no-reindex"   then opts[:reindex] = false
+  else usage_abort("unknown argument #{ARGV[i].inspect}")
+  end
+  i += 1
+end
+
+usage_abort("--day is required") if opts[:day].nil?
+usage_abort("--day must be a real calendar date, YYYYMMDD") unless SessionLedger.valid_day_id?(opts[:day])
+usage_abort("--match is required") if opts[:match].nil? || opts[:match].empty?
+
+plastic_home = File.expand_path(opts[:plastic_home] || ENV.fetch("PLASTIC_HOME", "~/.plastic"))
+store = opts[:store] || File.join(plastic_home, "store")
+templates = opts[:templates] || File.expand_path("../templates", __dir__)
+session = opts[:session] ? SessionLedger.short_session_id(opts[:session]) : nil
+
+target_store = store
+if opts[:project]
+  projects = StoreProvisioning.load_projects(plastic_home)
+  usage_abort("--project #{opts[:project]} is not a registered project") unless projects.key?(opts[:project])
+  target_store = File.join(plastic_home, "projects", opts[:project], "store")
+end
+
+# --- pick the target line ---------------------------------------------------
+
+day_dir = SessionLedger.day_dir(store, opts[:day])
+checklist = SessionLedger.checklist_path(store, opts[:day])
+items = SessionBackfill.read_items(day_dir)
+candidates = items.select do |item|
+  (session.nil? || item[:session] == session) && item[:summary].include?(opts[:match])
+end
+target = candidates.reverse.find { |item| item[:state] == :open } ||
+         candidates.reverse.find { |item| item[:state] == :pending }
+usage_abort("nothing to promote in #{opts[:day]} matching #{opts[:match].inspect}") if target.nil?
+
+# --- scaffold through new-intent ---------------------------------------------
+
+def slug_for(summary)
+  words = summary.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "").split("-").reject(&:empty?)
+  slug = words.first(5).join("-")
+  slug.empty? ? "item" : slug
+end
+
+new_intent = File.expand_path("new-intent", __dir__)
+out, err, status = Open3.capture3({ "RUBYOPT" => nil }, RbConfig.ruby, new_intent,
+                                  "--store", target_store, "--intent", target[:summary],
+                                  "--slug", slug_for(target[:summary]), "--templates", templates)
+unless status.success?
+  warn "promote-session-item: new-intent failed:"
+  warn err
+  warn out
+  exit 1
+end
+intent_dir = out.lines.last.to_s.strip
+usage_abort("new-intent printed no intent dir") if intent_dir.empty? || !Dir.exist?(intent_dir)
+intent_id = File.basename(intent_dir).split("--", 2).first
+
+# --- record the origin in the new intent (one atomic rewrite) -----------------
+
+intent_file = File.join(intent_dir, "#{File.basename(intent_dir)}.md")
+content = File.read(intent_file)
+parts = content.split(/^(---\s*\n)/, 3)
+if parts.length >= 4
+  parts[2] += "session_day: \"#{opts[:day]}\"\n"
+  content = parts[0] + parts[1] + parts[2] + parts[3] + parts[4].to_s
+end
+origin = "Promoted from the session ledger of #{opts[:day]}: #{target[:summary]}\n"
+content = content.sub(/^## Context\n/) { |heading| heading + origin }
+SessionBackfill.write_atomic(intent_dir, File.basename(intent_file), content)
+
+# --- register the intent under ## Future in the store's INDEX.md ----------------
+
+def register_in_index(index_path, intent_id, intent_dir, summary)
+  return unless File.exist?(index_path)
+
+  relative = "store/#{File.basename(intent_dir)}/#{File.basename(intent_dir)}.md"
+  entry = "- [#{intent_id} - #{summary}](#{relative}) - promoted from a session ledger\n"
+  content = File.read(index_path)
+  return if content.include?("(#{relative})")
+
+  updated = content.sub(/^## Future\n(?:\(no future intents\)\n)?/) { |heading| heading.sub(/\(no future intents\)\n/, "") + entry }
+  SessionBackfill.write_atomic(File.dirname(index_path), File.basename(index_path), updated)
+end
+
+register_in_index(File.join(File.dirname(target_store), "INDEX.md"), intent_id, intent_dir, target[:summary])
+
+# --- mark the line, note it, reindex ---------------------------------------------
+
+SessionLedger.set_state(checklist, from: target[:state], to: :promoted, session: target[:session],
+                        match: target[:summary])
+SessionLedger.append_line(SessionLedger.savepoint_path(store, opts[:day]),
+                          SessionLedger.savepoint_line("Note", target[:session], target[:project],
+                                                       "promoted \"#{target[:summary]}\" to intent #{intent_id}",
+                                                       now: Time.now))
+if opts[:reindex]
+  qmd_sync = File.expand_path("qmd-sync", __dir__)
+  system({ "RUBYOPT" => nil }, RbConfig.ruby, qmd_sync, "reindex", out: File::NULL, err: File::NULL) if File.exist?(qmd_sync)
+end
+puts intent_dir

package/scripts/rebuild-graph

@@ -82,7 +82,7 @@ class RebuildGraph
   end
 
   # Registered projects.yml slugs with no store directory on disk (legal;
-  # plastic-store-provisioning exists for exactly this state). Reported in the audit
+  # the plastic-doctor provisioning section exists for exactly this state). Reported in the audit
   # (intent 189 D5) so this never looks like a silent empty store.
   def missing_stores
     discovery[:missing]

package/scripts/roadmap-next

@@ -4,10 +4,10 @@
 
 # roadmap-next - thin CLI over RoadmapQueue (intent 148).
 #
-# The auto loop and plastic-roadmap-continuing both call this instead of ranking roadmap
+# The auto loop and plastic-intent-continuing both call this instead of ranking roadmap
 # liveness in prose. Queue mode (default) is for the auto loop: it breaks a tie
 # deterministically and reports the winner's frontier state. Which mode (--which) is for
-# plastic-roadmap-continuing: it returns tie_candidates so the skill's single ask can resolve
+# plastic-intent-continuing: it returns tie_candidates so the skill's roadmap route can resolve
 # a genuine tie.
 #
 # Usage:

package/scripts/rollback.rb

@@ -82,8 +82,6 @@ class Rollback < InstallerCore
     File.exist?(path) ? File.read(path).strip : nil
   end
 
-  private
-
   def flag_value(argv, name)
     i = argv.index(name)
     return nil unless i && argv[i + 1]
@@ -93,11 +91,52 @@ class Rollback < InstallerCore
   def switch_to(target, current)
     action = action_for(target, current)
     puts "#{action == "downgrade" ? "\u{23ea}" : "\u{23e9}"}  #{current} \u{2192} #{target} (#{action})"
-    cmd = ["npx", "#{PKG}@#{target}", "install", "--reinstall", "--ledger-action", action, "--claude"]
+    prepare_switch(target, current)
+    cmd = ["npx", "#{PKG}@#{target}", "install", "--reinstall", "--ledger-action", action, *harness_flags]
     puts "  $ #{cmd.join(" ")}"
     system(*cmd) ? 0 : 1
   end
 
+  # Before handing off to an older package (a downgrade), strip Plastic's own current hook
+  # registrations from every installed harness (intent 310, cut-inventory R2). The older
+  # installer purges only the names its own registry knows, so an entry this version
+  # registered would otherwise survive while the older manifest diff deletes its launcher,
+  # and the older doctor would then report an unowned plastic- command. The older installer
+  # registers its own set fresh on the cleaned file. Returns the paths it stripped.
+  def prepare_switch(target, current)
+    return [] unless action_for(target, current) == "downgrade"
+
+    stripped = []
+    installed_agents.each do |key|
+      agent = agents.find { |a| a[:key] == key }
+      next unless agent
+
+      case key
+      when "claude"
+        path = File.join(agent[:dir], "settings.json")
+        if File.exist?(path)
+          remove_claude_hooks(path)
+          stripped << path
+        end
+      when "codex"
+        path = agent[:home_dir] && File.join(agent[:home_dir], "hooks.json")
+        if path && File.exist?(path)
+          remove_codex_hooks(path)
+          stripped << path
+        end
+      end
+    end
+    stripped
+  end
+
+  # The install flags for every harness with a per-agent record (intent 310); Claude alone
+  # when nothing is recorded, matching the first-install default.
+  def harness_flags
+    keys = installed_agents
+    keys = ["claude"] if keys.empty?
+    keys.map { |k| "--#{k}" }
+  end
+
   def print_table(ledger, current)
     puts "\nPlastic version history (versions.json — append-only):\n\n"
     puts "    %-22s %-10s %s" % ["version", "action", "at"]

package/scripts/scaffold-intent

@@ -2,46 +2,38 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-# scaffold-intent (intent 213) - one CLI, three subcommands, each writes one lifecycle
-# artifact by copying or mechanically deriving it from an already-committed source. Every
-# field it writes is a verbatim copy or a mechanical derivation (a `git diff --stat`, a
-# supplied file's contents) of an already-committed artifact; no subcommand interprets or
-# invents prose. A field it cannot derive mechanically is left as the template's own stub
-# text instead of being guessed at.
+# scaffold-intent (intent 213; one verb since intent 308) - write an intent's judgment
+# documents from its record. `backfill` fills spec.md, plan.md, actions/ACTION_1.md, and
+# outcome.md wherever the file is missing or still the scaffold placeholder, from the
+# intent file, checklist.md, and the diff (BackfillIntent). Every section it writes is a
+# verbatim copy or a mechanical rendering of an already-committed artifact; a section with
+# no source keeps the template's own stub text. A hand-written file is never touched, and
+# there is no force flag: real content is edited by hand or not at all.
 #
-# Usage:
-#   scaffold-intent spec|checklist|outcome --store <path> --id <intent_id> [--force]
-#     [--test-summary <path>]   (outcome subcommand only)
+# `scripts/end-intent` runs the same writer at every close, so this CLI exists for the
+# doctor fix hint (backfilled_complete) and for filling an intent by hand before its close.
 #
-# Subcommand is the first positional argument. --store and --id are required for every
-# subcommand. --test-summary is valid only on the outcome subcommand; on spec or
-# checklist, or naming a path that does not exist, it is a usage error (exit 1). No other
-# flags exist: --store, --id, --force, and --test-summary (outcome only) are the whole
-# shipped surface (D5, a one-way door).
+# Usage:
+#   scaffold-intent backfill --store <path> --id <intent_id> --disposition delivered|abandoned
+#                            [--summary <text>]
 #
 # Exit codes:
-#   0  scaffolded
+#   0  written, or nothing left to write
 #   1  usage or path-resolution failure
-#   2  refused to overwrite real content without --force
-#   3  a prerequisite committed artifact is missing or still sentinel
-#
-# The actions/ rule (intent 133a, D11): scaffold-intent does not scaffold actions/ in any
-# form. Actions require judgment and stay entirely with the planner. No subcommand
-# creates the directory, writes a .gitkeep, or writes a sentinel-only ACTION_*.md.
+#   3  a source is unusable (the intent file is missing)
 #
-# outcome is an end-of-Exec step. Run it once the diff and the test summary exist, right
-# before plastic-intent-ending writes the narrative. Writing outcome.md makes the intent
-# read as Done to any stage-derived display (Bridge.derive_stage keys on outcome.md's
-# presence). This does NOT purge a bridge:
-# Bridge.purge_done_bridges keys on INDEX Active status plus lock presence, never on the
-# derived stage.
+# The spec, checklist, and outcome subcommands, --force, and --test-summary were removed
+# in 2.0 (intent 308): the backfill writer covers their two derivable targets and the
+# outcome diffstat, and nothing else called them.
 
 require_relative "lib/scaffold_intent"
+require_relative "lib/backfill_intent"
 
-SUBCOMMANDS = %w[spec checklist outcome].freeze
+SUBCOMMANDS = %w[backfill].freeze
+DISPOSITIONS = %w[delivered abandoned].freeze
 
 def parse_args(argv)
-  opts = { subcommand: nil, store: nil, id: nil, force: false, test_summary: nil }
+  opts = { subcommand: nil, store: nil, id: nil, disposition: nil, summary: nil }
   args = argv.dup
   opts[:subcommand] = args.shift
 
@@ -49,10 +41,10 @@ def parse_args(argv)
   while i < args.length
     arg = args[i]
     case arg
-    when "--store"        then opts[:store] = args[i += 1]
-    when "--id"            then opts[:id] = args[i += 1]
-    when "--force"         then opts[:force] = true
-    when "--test-summary"  then opts[:test_summary] = args[i += 1]
+    when "--store"       then opts[:store] = args[i += 1]
+    when "--id"          then opts[:id] = args[i += 1]
+    when "--disposition" then opts[:disposition] = args[i += 1]
+    when "--summary"     then opts[:summary] = args[i += 1]
     else
       usage_abort("unknown argument #{arg.inspect}")
     end
@@ -62,8 +54,8 @@ def parse_args(argv)
 end
 
 def usage
-  "usage: scaffold-intent spec|checklist|outcome --store <store_path> --id <intent_id> " \
-    "[--force] [--test-summary <path>]"
+  "usage: scaffold-intent backfill --store <store_path> --id <intent_id> " \
+    "--disposition delivered|abandoned [--summary <text>]"
 end
 
 def usage_abort(message)
@@ -75,11 +67,11 @@ end
 def main(argv)
   opts = parse_args(argv)
 
-  usage_abort("subcommand must be one of #{SUBCOMMANDS.join('|')}") unless SUBCOMMANDS.include?(opts[:subcommand])
+  usage_abort("subcommand must be #{SUBCOMMANDS.join('|')}") unless SUBCOMMANDS.include?(opts[:subcommand])
   usage_abort("--store is required") if opts[:store].nil? || opts[:store].empty?
   usage_abort("--id is required") if opts[:id].nil? || opts[:id].empty?
-  if opts[:test_summary] && opts[:subcommand] != "outcome"
-    usage_abort("--test-summary is valid only on the outcome subcommand")
+  unless DISPOSITIONS.include?(opts[:disposition])
+    usage_abort("--disposition must be one of #{DISPOSITIONS.join('|')}")
   end
 
   store = ScaffoldIntent.expand(opts[:store])
@@ -88,33 +80,15 @@ def main(argv)
   intent_dir, err = ScaffoldIntent.resolve_intent_dir(store, opts[:id])
   usage_abort(err) if intent_dir.nil?
 
-  test_summary_path = nil
-  if opts[:test_summary]
-    test_summary_path = ScaffoldIntent.expand(opts[:test_summary])
-    usage_abort("--test-summary path does not exist: #{test_summary_path}") unless File.exist?(test_summary_path)
-  end
+  result = BackfillIntent.run(intent_dir: intent_dir, store: store, id: opts[:id],
+                              disposition: opts[:disposition], summary: opts[:summary])
 
-  result =
-    case opts[:subcommand]
-    when "spec"
-      ScaffoldIntent.scaffold_spec(intent_dir: intent_dir, force: opts[:force])
-    when "checklist"
-      ScaffoldIntent.scaffold_checklist(intent_dir: intent_dir, force: opts[:force])
-    when "outcome"
-      ScaffoldIntent.scaffold_outcome(intent_dir: intent_dir, force: opts[:force], store: store,
-                                      id: opts[:id], test_summary: test_summary_path)
-    end
-
-  if result[:message]
-    if result[:code] == 0
-      puts result[:message]
-    else
-      warn "scaffold-intent: #{result[:message]}"
-    end
-  end
-  puts result[:path] if result[:path]
+  result[:written].each { |rel| puts "scaffold-intent: backfilled #{File.join(intent_dir, rel)}" }
+  result[:skipped].each { |rel| puts "scaffold-intent: kept #{rel} (real content)" }
+  result[:notes].each { |note| warn "scaffold-intent: #{note}" }
+  puts "scaffold-intent: nothing to backfill" if result[:written].empty? && result[:notes].empty?
 
-  exit result[:code]
+  exit(result[:notes].any? { |n| n.include?("intent file is missing") } ? 3 : 0)
 end
 
 main(ARGV) if $PROGRAM_NAME == __FILE__