@zalom/plastic 1.0.0-beta.34 → 1.0.0-beta.36

package/scripts/install.rb

@@ -14,6 +14,7 @@
 # so install.rb is the single file-syncer; the ledger action is contextual.
 
 require_relative "lib/installer_core"
+require_relative "lib/preflight"
 
 class Install < InstallerCore
   def cli(argv = ARGV)
@@ -22,6 +23,9 @@ class Install < InstallerCore
       return 0
     end
 
+    gate = preflight_gate
+    return gate unless gate.zero?
+
     force = argv.include?("--force")
     reinstall = argv.include?("--reinstall")
     ledger_action = flag_value(argv, "--ledger-action")
@@ -42,19 +46,19 @@ class Install < InstallerCore
       return 1
     end
 
-    run(selected: selected, force: force, reinstall: reinstall, ledger_action: ledger_action)
+    run(selected: selected, force: force, reinstall: reinstall, ledger_action: ledger_action, argv: argv)
     0
   end
 
   # Hermetic entrypoint (no prompting / no exit). Returns the per-agent results array.
-  def run(selected:, force: false, reinstall: false, ledger_action: nil)
+  def run(selected:, force: false, reinstall: false, ledger_action: nil, argv: ARGV, input: $stdin)
     fresh = !installed?
     mode = fresh ? :install : :update # :update here means "re-sync, skip bootstrap"
 
     distribute(mode)
     bootstrap if fresh
 
-    results = selected.map { |key| install_for_agent(key, force) }
+    results = selected.map { |key| install_for_agent(key, force, argv: argv, input: input, reinstall: reinstall) }
 
     action = ledger_action || (fresh ? "install" : "reinstall")
     ledger_append(version, action)
@@ -72,8 +76,37 @@ class Install < InstallerCore
     File.exist?(path) ? File.read(path).strip : nil
   end
 
+  # Injectable pre-flight gate: real probes as default args, printing to an
+  # injectable `out:` IO so this is hermetically testable via StringIO. Returns
+  # 1 (stop the install) when Ruby is missing/too-old, else 0.
+  def preflight_gate(ruby_version: RUBY_VERSION, node_version: node_probe, git_present: git_probe,
+                      mise_present: mise_probe, out: $stderr)
+    result = Preflight.check(ruby_version: ruby_version, node_version: node_version,
+                              git_present: git_present, mise_present: mise_present)
+    result[:messages].each { |message| out.puts(message) }
+    result[:fatal] ? 1 : 0
+  end
+
   private
 
+  def node_probe
+    `node --version`.strip
+  rescue StandardError
+    ""
+  end
+
+  def git_probe
+    !`command -v git`.strip.empty?
+  rescue StandardError
+    false
+  end
+
+  def mise_probe
+    !`command -v mise`.strip.empty?
+  rescue StandardError
+    false
+  end
+
   def flag_value(argv, name)
     i = argv.index(name)
     return nil unless i && argv[i + 1]
@@ -119,9 +152,12 @@ class Install < InstallerCore
         --alpha       Alpha channel
 
       Other options:
-        --reinstall   Re-sync core files for the installed version (repair). Store untouched.
-        --force       Overwrite existing files without prompting
-        -h, --help    Show this help
+        --reinstall          Re-sync core files for the installed version (repair). Store untouched.
+        --force              Overwrite existing files without prompting
+        --statusline VALUE   keep or plastic. If an existing statusline is found, this
+                             skips the interactive prompt. Interactive sessions ask by
+                             default; non-interactive sessions default to keep.
+        -h, --help           Show this help
 
       Notes:
         Install is one-shot. If Plastic is already installed, use `update` to upgrade or

package/scripts/lib/bridge.rb

@@ -921,6 +921,49 @@ module Bridge
       "(blocked edit: #{file_abs})"
   end
 
+  # --- Solo-mode detection (intent 128) ---------------------------------------
+  #
+  # Positive-only confirmation that exactly one session is delivering, from the
+  # durable delivery.lock files (never the /tmp bridge cache, D2). Used to relax
+  # the two ARBITRATION gates (lock_gate_decision, worktree_gate_decision) from
+  # a hard deny to an advisory allow when there is nothing to arbitrate.
+  #
+  # SOLO iff exactly ONE fresh delivery.lock exists across scan_roots, that
+  # lock's owner_session equals the resolved session, and its delegates array
+  # is empty. Any ambiguity (more than one fresh lock, including several under
+  # the SAME owner_session, which reads as parallel-in-play), a foreign owner,
+  # a non-empty delegates array, a blank/unresolvable session, or any error
+  # during the scan all return false (fail-closed direction preserved).
+  def self.solo_delivery?(scan_roots:, session:, ttl: Lock::TTL_SECONDS, now: Time.now)
+    return false if blank?(session)
+
+    lock_dirs = Array(scan_roots).compact.flat_map { |root|
+      Dir.glob(File.join(File.expand_path(root), "*", "delivery.lock"))
+    }.uniq.map { |lock_file| File.dirname(lock_file) }
+
+    fresh_dirs = lock_dirs.select { |dir| Lock.fresh?(dir, ttl: ttl, now: now) }
+    fresh_locks = fresh_dirs.map { |dir| Lock.read(dir) }
+
+    # A fresh-but-unreadable (corrupt) lock is real ambiguity, not an absence:
+    # dropping it via filter_map could leave exactly one READABLE lock and
+    # misconfirm solo while a second, unreadable-but-live lock is in play.
+    # Any unreadable fresh lock keeps this fail-closed (review finding 2).
+    return false if fresh_locks.any?(&:nil?)
+    return false unless fresh_locks.length == 1
+
+    lock = fresh_locks.first
+    lock["owner_session"].to_s == session.to_s && Array(lock["delegates"]).empty?
+  rescue StandardError
+    false
+  end
+
+  # One terse advisory line (no em-dashes), then ALLOW (nil). Shared by both
+  # arbitration gates so a relaxed deny always logs the same shape.
+  def self.solo_allow(id, reason)
+    $stderr.puts "plastic: solo delivery confirmed for intent #{id} (#{reason}); allowing"
+    nil
+  end
+
   # --- Fail-closed lock gate (intent 96) -------------------------------------
 
   # Returns a reason String to BLOCK, or nil to ALLOW. Decides from the
@@ -931,7 +974,7 @@ module Bridge
   # target's lock names as owner or delegate (even when stale: a stale lock is
   # still its owner's until an explicit takeover).
   def self.lock_gate_decision(bridge_data, file_path, session: nil,
-                              ttl: Lock::TTL_SECONDS, now: Time.now)
+                              ttl: Lock::TTL_SECONDS, now: Time.now, home: Dir.home)
     return nil if blank?(file_path)
 
     target_dir = intent_dir_for(file_path)
@@ -943,23 +986,34 @@ module Bridge
     sess = session
     sess = bridge_data["session"] if blank?(sess) && bridge_data.is_a?(Hash)
 
+    # Solo-mode detection (intent 128): scan this intent's store plus the
+    # global store under `home` for fresh delivery locks. Computed once; used
+    # at every arbitration deny below to relax a hard deny to an advisory
+    # allow when solo delivery is positively confirmed.
+    scan_roots = [store, File.join(File.expand_path(home), ".plastic", "store")]
+    solo = solo_delivery?(scan_roots: scan_roots, session: sess, ttl: ttl, now: now)
+
     lock = Lock.read(target_dir)
     if lock
       return nil if Lock.authorized?(lock, sess)
       if Lock.fresh?(target_dir, ttl: ttl, now: now)
+        return solo_allow(id, "fresh delivery lock") if solo
         return "intent #{id} delivery lock is held by session " \
                "#{lock['owner_session']}. Back off; if you are the owner's " \
                "subagent, the owner must run: plastic-lock delegate " \
                "--intent-dir #{target_dir} --session <your-session-id>. " \
                "Inspect with /plastic-lock status"
       end
+      return solo_allow(id, "stale delivery lock") if solo
       return "intent #{id} has a stale delivery lock (owner " \
              "#{lock['owner_session']}); run /plastic-lock reclaim to take " \
              "it over, or /plastic-lock fix"
     end
     if Lock.corrupt?(target_dir)
+      return solo_allow(id, "unreadable delivery.lock") if solo
       return "delivery.lock for intent #{id} is unreadable; run /plastic-lock fix"
     end
+    return solo_allow(id, "no delivery lock") if solo
     "no delivery lock held for intent #{id}; run /plastic-intent-starting " \
       "to lock and begin"
   end
@@ -1012,6 +1066,19 @@ module Bridge
     under_own_intent = intent_dir_abs &&
                        (file_abs == intent_dir_abs || file_abs.start_with?("#{intent_dir_abs}/"))
 
+    # Solo-mode detection (intent 128): current session first, else the
+    # bridge's own session; scan roots are this intent's store, the global
+    # store under `home`, AND the EDIT TARGET's own store (when the target
+    # lives inside a store dir), so a live foreign lock on the intent being
+    # edited is never invisible to the scan just because it belongs to a
+    # different project than the acting bridge's own store (review finding 1;
+    # duplicate roots are harmless, solo_delivery? dedupes). Computed once;
+    # used by both rules below.
+    sess = blank?(current_session) ? bridge_data["session"] : current_session
+    target_store = parse_store_target(file_abs, plastic_home)&.fetch(:store, nil)
+    scan_roots = [store, File.join(plastic_home, "store"), target_store]
+    solo = solo_delivery?(scan_roots: scan_roots, session: sess)
+
     # Rule 1 (fixed in intent 108, D7): confinement applies ONLY to paths
     # inside the project repo. The repo root is derived from the provisioned
     # code worktree path, which is <repo>/.claude/worktrees/{id}--{slug} by
@@ -1029,6 +1096,7 @@ module Bridge
         inside_code = file_abs == code_abs || file_abs.start_with?("#{code_abs}/")
         if inside_repo && !inside_code
           id = intent_info["id"]
+          return solo_allow(id, "worktree confinement") if solo
           return "intent #{id} is isolated to its worktree - edit project code " \
                  "inside #{code_abs}, not the shared checkout. (blocked edit: #{file_abs})"
         end
@@ -1040,7 +1108,10 @@ module Bridge
       reason = non_owner_store_edit_reason(file_abs, plastic_home, intent_dir_abs,
                                            home: home, current_session: current_session,
                                            own_session: bridge_data["session"])
-      return reason if reason
+      if reason
+        return solo_allow(intent_info["id"], "non-owner store edit") if solo
+        return reason
+      end
     end
 
     nil
@@ -1173,7 +1244,11 @@ module Bridge
       c = line[i]
       case state
       when :single
-        out << " "
+        if c == "'" || c == "<" || c == ">"
+          out << " "
+        else
+          out << c
+        end
         state = :normal if c == "'"
         i += 1
       when :double
@@ -1181,7 +1256,11 @@ module Bridge
           out << "  "
           i += 2
         else
-          out << " "
+          if c == '"' || c == "<" || c == ">"
+            out << " "
+          else
+            out << c
+          end
           state = :normal if c == '"'
           i += 1
         end
@@ -1191,7 +1270,7 @@ module Bridge
         elsif c == '"'
           out << " "; state = :double; i += 1
         elsif c == "<" && line[i + 1] == "<"
-          m = line[i..].match(/\A<<(-?)\s*("|')?([A-Za-z_][A-Za-z0-9_]*)\2?/)
+          m = line[i..].match(/\A<<(-?)\s*("|')?([A-Za-z0-9_][A-Za-z0-9_]*)\2?/)
           if m
             openers << { word: m[3], dash: m[1] == "-" }
             out << (" " * m[0].length)

package/scripts/lib/installer_core.rb

@@ -161,6 +161,37 @@ class InstallerCore
     nums.select { |n| n >= 1 && n <= agents.size }.map { |n| agents[n - 1][:key] }
   end
 
+  # Resolve whether install should keep the user's existing statusline or switch it
+  # to Plastic's. Pure function of (settings file, argv, input, reinstall): no writes,
+  # so it stays fully unit-testable apart from merge_claude_hooks.
+  def statusline_choice(settings_path, argv: [], input: $stdin, reinstall: false)
+    existing_command = read_json_safe(settings_path)&.dig("statusLine", "command").to_s
+    return :plastic if existing_command.empty?
+    return :plastic if existing_command.include?("plastic-")
+
+    idx = argv.index("--statusline")
+    flag = idx && argv[idx + 1]
+    return flag.to_sym if %w[keep plastic].include?(flag)
+
+    return :keep if reinstall
+    return prompt_statusline(input: input) if input.tty?
+
+    :keep
+  end
+
+  def prompt_statusline(input: $stdin)
+    return :keep unless input.tty?
+
+    puts "An existing statusline was found in your settings.\n\n"
+    puts "  1. Keep my statusline (Plastic will not change it)"
+    puts "  2. Switch to Plastic's statusline"
+    puts
+    print "Select (1 or 2, Enter to keep): "
+    answer = input.gets&.strip
+
+    answer == "2" ? :plastic : :keep
+  end
+
   # --- Distribution phase ---
 
   def distribute(mode)
@@ -197,6 +228,7 @@ class InstallerCore
   def core_files
     {
       "PLASTIC.md" => "PLASTIC.md",
+      "PLASTIC-reference.md" => "PLASTIC-reference.md",
       "deprecations.yml" => "deprecations.yml",
       "scripts/folgezettel-id" => "scripts/folgezettel-id",
       "scripts/read-config" => "scripts/read-config",
@@ -249,6 +281,7 @@ class InstallerCore
       "scripts/lib/store_provisioning.rb" => "scripts/lib/store_provisioning.rb",
       "scripts/provision-project-store" => "scripts/provision-project-store",
       "scripts/lib/installer_core.rb" => "scripts/lib/installer_core.rb",
+      "scripts/lib/preflight.rb" => "scripts/lib/preflight.rb",
       "scripts/install.rb" => "scripts/install.rb",
       "scripts/update.rb" => "scripts/update.rb",
       "scripts/uninstall.rb" => "scripts/uninstall.rb",
@@ -321,7 +354,7 @@ class InstallerCore
     (data["files"] || {}).keys
   end
 
-  def install_for_agent(key, force)
+  def install_for_agent(key, force, argv: [], input: $stdin, reinstall: false)
     config = agent_config(key)
     return { agent: config[:name], success: false, reason: "Unknown agent" } unless config
 
@@ -334,7 +367,7 @@ class InstallerCore
     old_files = manifest_files(manifest_path_for(key, config))
 
     result = case key
-             when "claude" then install_claude(config, force)
+             when "claude" then install_claude(config, force, argv: argv, input: input, reinstall: reinstall)
              when "codex" then install_codex(config, force)
              when "hermes" then install_hermes(config, force)
              end
@@ -363,7 +396,7 @@ class InstallerCore
     removed
   end
 
-  def install_claude(config, force)
+  def install_claude(config, force, argv: [], input: $stdin, reinstall: false)
     hooks_dir = File.join(config[:dir], "hooks")
     skills_root = File.join(config[:dir], "skills")
     plastic_dir = File.join(config[:dir], "plastic")
@@ -406,7 +439,8 @@ class InstallerCore
 
     # Merge hooks + statusline into settings.json (no plugin registration)
     settings_path = File.join(config[:dir], "settings.json")
-    merge_claude_hooks(settings_path)
+    choice = statusline_choice(settings_path, argv: argv, input: input, reinstall: reinstall)
+    merge_claude_hooks(settings_path, choice: choice)
 
     # Write manifest
     manifest_path = File.join(plastic_dir, "manifest.json")
@@ -572,7 +606,7 @@ class InstallerCore
 
   # --- settings.json merge (read-modify-write, never clobber) ---
 
-  def merge_claude_hooks(settings_path)
+  def merge_claude_hooks(settings_path, choice: :plastic)
     settings = read_json_safe(settings_path) || {}
     return if settings.nil?
 
@@ -614,7 +648,7 @@ class InstallerCore
       File.write(File.join(cache_dir, "original-statusline.json"), JSON.pretty_generate(existing_status))
     end
 
-    settings["statusLine"] = { "type" => "command", "command" => "#{hook_dir}/plastic-statusline" }
+    settings["statusLine"] = { "type" => "command", "command" => "#{hook_dir}/plastic-statusline" } if choice == :plastic
 
     # No plugin/marketplace registration: skills are flat personal skills
     # (plastic-<name>/) discovered directly from ~/.claude/skills.

package/scripts/lib/power_tools.rb

@@ -52,24 +52,26 @@ module PowerTools
     false
   end
 
-  # Recommendation text for whichever tools are present, joined by newlines, or
-  # nil when none are. One recommendation line per present tool.
-  def mandate(cwd:, qmd_detector: QmdSync.method(:detect), serena_detector: nil)
-    lines = []
-
-    if qmd?(detector: qmd_detector)
-      lines << "QMD is available: prefer `qmd search` / `qmd query` over the " \
-               "`plastic-*` collections to check for existing or related intents " \
-               "before treating work as new."
-    end
+  QMD_OBLIGATION = "prefer `qmd search` / `qmd query` over the `plastic-*` " \
+                   "collections to check for existing or related intents before " \
+                   "treating work as new"
+  SERENA_OBLIGATION = "prefer its symbolic tools (find_symbol / get_symbols_overview / " \
+                       "find_referencing_symbols) for code navigation"
 
+  # Recommendation text for whichever tools are present, or nil when none are.
+  # Both present collapse to ONE combined line naming both obligations (no
+  # embedded newline); one present returns that tool's own line; neither
+  # returns nil.
+  def mandate(cwd:, qmd_detector: QmdSync.method(:detect), serena_detector: nil)
+    qmd_present = qmd?(detector: qmd_detector)
     serena_present = serena_detector ? !!serena_detector.call : serena?(cwd: cwd)
-    if serena_present
-      lines << "Serena is available: prefer its symbolic tools (find_symbol / " \
-               "get_symbols_overview / find_referencing_symbols) for code navigation."
-    end
 
-    return nil if lines.empty?
-    lines.join("\n")
+    if qmd_present && serena_present
+      "QMD and Serena are available: #{QMD_OBLIGATION}, and #{SERENA_OBLIGATION}."
+    elsif qmd_present
+      "QMD is available: #{QMD_OBLIGATION}."
+    elsif serena_present
+      "Serena is available: #{SERENA_OBLIGATION}."
+    end
   end
 end

package/scripts/lib/preflight.rb

@@ -0,0 +1,79 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "rubygems"
+
+# Pure, dependency-injected pre-flight checks for Plastic's runtime dependencies
+# (intent 38). Takes injected probes (ruby version, node version, git presence,
+# mise presence) and returns a plain decision: ok / fatal plus branded messages.
+#
+# No I/O, no shelling out, no ENV reads here. Callers (scripts/install.rb,
+# bin/plastic.js) own the impure probing and the printing, so this module stays
+# hermetically testable. Voice matches boot_banner.rb (understated, "Plastic ..."
+# prefix); no em-dash, no en-dash in any message.
+module Preflight
+  module_function
+
+  RUBY_FLOOR = "3.0.0"
+  NODE_FLOOR = 18
+  RUBY_PIN = "3.3"
+
+  def check(ruby_version:, node_version:, git_present:, mise_present:)
+    messages = []
+
+    ruby_message = ruby_issue(ruby_version, mise_present)
+    fatal = !ruby_message.nil?
+    messages << ruby_message if ruby_message
+
+    node_message = node_issue(node_version)
+    messages << node_message if node_message
+
+    git_message = git_issue(git_present)
+    messages << git_message if git_message
+
+    { ok: messages.empty?, fatal: fatal, messages: messages }
+  end
+
+  def ruby_issue(ruby_version, mise_present)
+    parsed = safe_version(ruby_version)
+    return nil if parsed && parsed >= safe_version(RUBY_FLOOR)
+
+    lines = []
+    lines << "Plastic needs Ruby #{RUBY_FLOOR} or newer to run its scripts (found #{found(ruby_version)})."
+    lines << "Install a pinned Ruby with mise:"
+    lines << "  curl https://mise.run | sh        # only if mise is not installed yet" unless mise_present
+    lines << "  mise use --global ruby@#{RUBY_PIN}"
+    lines << "Then re-run the Plastic installer."
+    lines.join("\n")
+  end
+
+  def node_issue(node_version)
+    parsed = safe_version(strip_leading_v(node_version))
+    return nil if parsed && parsed >= safe_version(NODE_FLOOR.to_s)
+
+    "Plastic works best on Node #{NODE_FLOOR} or newer (found #{found(node_version)}). " \
+      "Pin it with mise: mise use --global node@25"
+  end
+
+  def git_issue(git_present)
+    return nil if git_present
+
+    "Plastic uses git for its store and worktrees (git was not found). " \
+      "Install git, e.g. macOS: xcode-select --install"
+  end
+
+  def safe_version(str)
+    Gem::Version.new(str.to_s)
+  rescue ArgumentError
+    nil
+  end
+
+  def strip_leading_v(str)
+    str.to_s.strip.sub(/\Av/, "")
+  end
+
+  def found(value)
+    text = value.to_s.strip
+    text.empty? ? "not found" : text
+  end
+end

package/skills/auto/SKILL.md

@@ -76,17 +76,10 @@ ruby -r ~/.plastic/scripts/lib/bridge -e \
 Replace `<ID>`, `<STORE>` (e.g. `~/.plastic/projects/<slug>/store` or `~/.plastic/store`),
 `<dir>` (the `ID--slug` directory), and `<name>`. The first argument is the session id you
 want the bridge keyed by: pass the hook stdin `session_id` when you have it, otherwise
-`ENV["CLAUDE_CODE_SESSION_ID"]`, otherwise `nil`. `arm_auto` calls `resolve_session`, which
-picks the first non-empty of: the explicit id you pass -> `CLAUDE_CODE_SESSION_ID` -> a
-deterministic derived key (a hash of the store and intent id).
-It never returns nil, so the gate engages even when every session env var is empty; the call
-never needs a non-empty session env var to function. Arming prints a one-line notice to
-stderr when it falls through to the derived key.
-
-Arming acquires the durable `delivery.lock` in the intent dir, keyed by that resolved
-session. Ownership is session-keyed, not process-keyed, so the arm one-liner exiting
-immediately is fine by construction: the lock stays yours for every later tool call in this
-session. A failed arm raises with a message naming the resolving `plastic-lock` verb.
+`ENV["CLAUDE_CODE_SESSION_ID"]`, otherwise `nil`. Arming always succeeds and acquires the
+durable `delivery.lock` in the intent dir. For the `resolve_session` fallback chain
+(why arming never needs a non-empty session env var, and what the lock ownership model
+implies for later tool calls) read `references/end-tail.md`.
 
 **Hard rule for the rest of this run:** do NOT edit project code (anything outside the
 intent directory / `~/.plastic/`) until `plan.md` AND `checklist.md` exist for the intent.
@@ -165,6 +158,10 @@ Filesystem fallback (ledger missing only):
 
 Announce which stage you're entering and why.
 
+Notify user (What briefing): brief per `references/human-report-contract.md`
+(State: the work picked up and why it matters now; Risk: scope uncertainty; Call: confirm
+this is worth doing, or proceed).
+
 ## Why Completion (Autonomous)
 
 When entering at Why stage:
@@ -179,6 +176,9 @@ When entering at Why stage:
 5. Make decisions — pick best option, document in `## Context > ### Decisions` with rationale
 6. Log all autonomous decisions in `## Insights` with `(autonomous)` marker: "Decision: chose X because Y (autonomous)"
 7. Write `spec.md` — consolidated specification
+8. Notify user (Why briefing): brief per `references/human-report-contract.md`
+   (State: the approach chosen, one line; Risk: the main trade-off; Call: the one decision
+   needed, approve or pick an option).
 
 Then proceed to How.
 
@@ -193,6 +193,9 @@ only (S/M leave the directory empty).
 2. Otherwise, write `plan.md` directly — implementation plan with numbered tasks
 3. Write `ACTION_N.md` files into the existing `actions/` directory (one per task, self-contained) — L only
 4. Write `checklist.md` — execution registry with checkboxes covering all actions
+5. Notify user (How briefing): brief per `references/human-report-contract.md`
+   (State: the plan shape, task count and what it builds; Risk: the riskiest task or
+   dependency; Call: approve the plan to build).
 
 Then proceed to Exec.
 
@@ -216,6 +219,9 @@ If the plan calls for creating a new project (the intent is an implementation in
 4. Check off items in `checklist.md` as completed
 5. Append observations to `## Insights` with `(autonomous)` marker
 6. Sub-agents can be spawned for parallel actions (one agent per action)
+7. Notify user (Exec briefing): brief per `references/human-report-contract.md`
+   (State: what got built and the test result; Risk: residual failures or deviations;
+   Call: go to review, or done).
 
 ## Permission Model — Safe-by-Default
 
@@ -281,36 +287,27 @@ During initial project creation, all decisions are non-destructive by definition
    ```bash
    ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.disarm_auto(ENV["CLAUDE_CODE_SESSION_ID"], intent_id: "<ID>")'
    ```
-   Disarm runs the ordered End tail: it releases the worktrees first, then clears the
-   intent's `delivery.lock` (and the bridge's lock cache), and only then is the bridge
-   purge-eligible. Disarming also purges stale bridge files from the temp directory
-   automatically (it keeps the current bridge, any live run, and any bridge whose intent
-   still holds a delivery lock), so no manual `/tmp` cleanup is needed.
-
-   **Worktree cleanup (mandatory, intent 73c3).** Disarming performs the worktree release:
-   `disarm_auto` calls `Worktree.release`, which removes both per-intent worktrees (the code
-   worktree under `<repo>/.claude/worktrees/{id}--{slug}` and the paired store worktree under
-   `<plastic_home>/.worktrees/{id}--{slug}`), prunes both repos, and clears the worktree block
-   from the bridge. This is the plain remove path: the disarm route does NOT merge, so use it
-   only when no release merges the branch (the branch survives and can be reclaimed).
-
-   When the work is being shipped through a release, do NOT rely on this plain remove. The
-   release path (step 4 above, via `plastic-releasing`) is responsible for merging the intent's
-   code branch (`plastic/{id}--{slug}`) back to the repo's default branch BEFORE the worktree is
-   removed, so the integrated work is not lost. It does this with `Worktree.finish(bridge_data,
-   merge: true)` (merge-then-remove). Never leave an orphaned worktree, and run `git worktree
-   prune` if you hit a stale reference.
-9. QMD reindex LAST (canonical End tail). AFTER disarm has released the worktrees, cleared the
-   `delivery.lock`, and purged the bridge, refresh the QMD search index for this store (no-op when
-   QMD is absent). It runs in the background so it never blocks the turn:
+   Disarm runs the ordered End tail (release worktrees, then clear the `delivery.lock`,
+   then the bridge becomes purge-eligible) and performs the mandatory worktree cleanup
+   (intent 73c3): both per-intent worktrees are removed and both repos pruned. This is
+   the plain remove path (no merge); when the work ships through a release, the release
+   path merges the branch BEFORE the worktree is removed instead of relying on this step.
+   Never leave an orphaned worktree, and run `git worktree prune` if you hit a stale
+   reference. For the full ordering rationale and the release-vs-plain-disarm
+   distinction, read `references/end-tail.md`.
+9. QMD reindex LAST (canonical End tail), run only after disarm has released the
+   worktrees, cleared the `delivery.lock`, and purged the bridge. It runs in the
+   background so it never blocks the turn:
    ```bash
    ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async
    ```
-   Completion is the lifecycle event that keeps the search index fresh. `<store-root>` is the store
-   that holds this intent (the global store or the project store). The reindex is the LAST End-tail
-   step, run after purge, so the index never references a bridge or lock that is about to disappear
-   (see PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`).
-10. Notify user: "Intent [ID] — [name] delivered. [1-2 sentence summary]. See outcome.md for details."
+   `<store-root>` is the store that holds this intent (the global store or the project
+   store); the command is a no-op when QMD is absent. For why the reindex must be last
+   (so the index never references a bridge or lock about to disappear), read
+   `references/end-tail.md`.
+10. Notify user (Done briefing): brief per `references/human-report-contract.md`
+    (State: the delivered impact; Risk: residual risk; Call: the decision left to you, merge,
+    release, or accept). See `outcome.md` for details.
 
 ## Error Handling
 
@@ -324,3 +321,8 @@ If the agent gets stuck (can't resolve a gap, dependency is missing, tests fail
 
 - Read `references/agent-architecture.md` for the full team model (the 5-role enforcer-led team, per-stage handoffs, gate ownership, headless note, solo fallback) and the orchestrator hierarchy (Main Orchestrator, Project Orchestrators, coordination loop) when spinning up the team or understanding autonomous delivery scope
 - Read `references/tiers.md` for the extended per-tier walkthrough (S/M/L worked examples, the collapsed one-thinker flow, the QMD-skip case for S) and rationale
+- Read `references/human-report-contract.md` for the human-facing per-stage briefing (the
+  State/Risk/Call skeleton used at each "Notify user" step above, and how it differs from the
+  internal `agent-report-contract.md`)
+- Read `references/end-tail.md` for the `resolve_session` fallback chain and the disarm
+  ordering / worktree cleanup / QMD reindex rationale referenced above