@zalom/plastic 1.9.0 → 1.11.0

package/scripts/lib/start_intent.rb

@@ -0,0 +1,296 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "bridge"
+require_relative "lock"
+require_relative "intent_validator"
+require_relative "spec_header"
+require_relative "outcome_guard"
+require_relative "scaffold_intent"
+
+# StartIntent - all logic for `scripts/start-intent` (intent 213, group 2). Boards a
+# session onto an intent: arm the delivery lock, then print a read-only resume-station
+# report. This is the highest-risk surface in this action set because it composes lock
+# arbitration; the rule for that surface is compose the existing primitives, add nothing
+# (spec D6).
+#
+# NEVER REIMPLEMENTS LOCK ARBITRATION. Arming is `Bridge.arm_auto` or `Bridge.arm_guided`
+# and nothing else acquires anything: no new arming logic, no retry loop, no takeover path.
+# This module NEVER calls the Lock module's release or takeover operations. That unguarded
+# read-modify-write gap is parked intent 254's territory; start-intent reports and refuses,
+# it never repairs a lock. Read-only lock inspection (`Lock.path`, `Lock.read`,
+# `Lock.fresh?`, `Lock.authorized?`) is expected and used below.
+#
+# DETERMINISM CRITERION: every value this module prints is read from already-committed
+# files or from `Bridge.arm_*`'s own return value. No model inference, no free-text
+# generation.
+#
+# Pure and dependency-injected: never calls `exit` or `abort`, never reads `ARGV` or `ENV`
+# directly. Seams: `armer:` (a lambda dispatching on mode to the two real Bridge methods),
+# plus session/harness/thread values passed in as arguments rather than read from ENV here.
+# Reading ENV for harness detection happens in the CLI (`scripts/start-intent`) and is
+# passed down.
+module StartIntent
+  module_function
+
+  EXIT_OK = 0
+  EXIT_USAGE = 1
+  EXIT_HELD = 3
+  EXIT_UNRESOLVED = 4
+
+  # --- Step 0: resolve inputs -------------------------------------------------------
+
+  # `name:` for the arm call, deterministically: the intent file frontmatter's `intent:`
+  # field, or the directory basename when the frontmatter is unreadable or blank. Never
+  # invents a name.
+  def resolve_name(intent_dir)
+    fm = IntentValidator.parse_frontmatter(Bridge.intent_file(intent_dir))
+    name = fm.is_a?(Hash) ? fm["intent"] : nil
+    Bridge.blank?(name) ? File.basename(intent_dir) : name
+  end
+
+  # Session resolution order: explicit --session, else CLAUDE_CODE_SESSION_ID (passed in
+  # as env_session, never read from ENV here), else nil. Deliberately NO fallback to the
+  # lock's own recorded owner (unlike end-intent's resolve_end_session): arming as an
+  # owner you cannot prove you are is wrong.
+  def resolve_session(explicit, env_session)
+    return explicit.to_s.strip unless Bridge.blank?(explicit)
+    return env_session.to_s.strip unless Bridge.blank?(env_session)
+    nil
+  end
+
+  # Harness/thread detection, mirroring skills/auto/SKILL.md's arm-the-lifecycle-gate
+  # snippet exactly: a non-empty CODEX_THREAD_ID means codex (thread = that id); else a
+  # non-empty CLAUDE_CODE_SESSION_ID means claude (thread = nil); else both nil. Pure:
+  # takes the raw ENV strings as arguments, never reads ENV itself.
+  def resolve_harness(codex_thread_id, claude_session_id)
+    codex = codex_thread_id.to_s.strip
+    claude = claude_session_id.to_s.strip
+    return { harness: "codex", thread: codex } unless codex.empty?
+    return { harness: "claude", thread: nil } unless claude.empty?
+    { harness: nil, thread: nil }
+  end
+
+  # --- Step 1: pre-flight lock read (read-only, before arming) ---------------------
+  #
+  # Mirrors the READ-ONLY half of scripts/end-intent's preflight_lock_verdict, minus its
+  # takeover branch (start-intent never takes over). Returns [verdict, lock_or_nil]:
+  #   :proceed    no lock, or this session already owns/delegates it
+  #   :corrupt    a lock file exists but Lock.read cannot parse it (exit 4, unconditional;
+  #               unlike end-intent, freshness is never consulted for a corrupt lock,
+  #               because there is no repair path here to reach for a stale one)
+  #   :no_session a lock file exists and no session identity resolved from any source
+  #               (exit 4)
+  #   :held       a FRESH foreign lock (exit 4... exit 3, before ever calling the armer)
+  #   :stale      a STALE foreign lock: fall through to arming, which arbitrates it (and
+  #               raises Bridge::LockHeldError with the reclaim hint) itself
+  def preflight_verdict(intent_dir, session)
+    return [:proceed, nil] unless File.exist?(Lock.path(intent_dir))
+
+    lock = Lock.read(intent_dir)
+    return [:corrupt, nil] if lock.nil?
+    return [:no_session, lock] if Bridge.blank?(session)
+    return [:proceed, lock] if Lock.authorized?(lock, session)
+    return [:held, lock] if Lock.fresh?(intent_dir)
+    [:stale, lock]
+  end
+
+  def corrupt_message(intent_dir)
+    "start-intent: the delivery lock at #{Lock.path(intent_dir)} exists but its content " \
+      "will not parse (corrupt); refusing to arm since another session may still be " \
+      "heartbeating it. Run /plastic-doctor check the lock status, or plastic-lock fix " \
+      "once it is confirmed safe."
+  end
+
+  def no_session_message(intent_dir)
+    "start-intent: a delivery lock exists at #{Lock.path(intent_dir)} but no session " \
+      "identity could be resolved (--session or CLAUDE_CODE_SESSION_ID are both blank); " \
+      "refusing rather than guessing. Pass --session explicitly."
+  end
+
+  def held_message(intent_dir, lock, harness:)
+    owner = lock.is_a?(Hash) ? lock["owner_session"] : nil
+    "start-intent: delivery lock for #{File.basename(intent_dir)} is held by a live " \
+      "session (#{owner}); run #{Bridge.skill_ref('plastic-doctor', harness: harness)} " \
+      "check the lock status"
+  end
+
+  # --- Step 2: arm -------------------------------------------------------------------
+
+  # Default arm seam: dispatches on mode to the two real Bridge methods. Nothing else
+  # acquires anything.
+  def default_armer
+    lambda do |mode, session:, intent_id:, intent_dir:, store:, name:, harness:, agent:,
+               model:, thread:|
+      case mode
+      when "auto"
+        Bridge.arm_auto(session, intent_id: intent_id, intent_dir: intent_dir, store: store,
+                        name: name, harness: harness, agent: agent, model: model, thread: thread)
+      when "guided"
+        Bridge.arm_guided(session, intent_id: intent_id, intent_dir: intent_dir, store: store,
+                          name: name, harness: harness, agent: agent, model: model, thread: thread)
+      end
+    end
+  end
+
+  # --- Step 3: the resume-station report (read-only, after arming) -----------------
+
+  # Count-only helper for the printed "actions/: <n> real action file(s)" line. The
+  # STATION gate (whether How is delivered) is decided exclusively by
+  # Bridge.has_real_action?, called separately in build_report; this exists only to render
+  # a number and must never be used for any pass/fail decision.
+  def real_action_count(intent_dir)
+    Dir.glob("#{intent_dir}/actions/*.md").count do |f|
+      File.file?(f) && File.size(f) > 0 && Bridge.stage_file_present?(f)
+    end
+  rescue StandardError
+    0
+  end
+
+  # Classify outcome.md into one of three states, per the spec's outcome.md nuance:
+  # `scaffold-intent outcome` writes a real (non-sentinel) outcome.md while leaving the
+  # frontmatter disposition at the template placeholder `delivered|abandoned`, so a naive
+  # sentinel check would misreport that as Done. Returns [state, reason]:
+  #   "not_started" the sentinel is still present (or the file is absent), reason nil
+  #   "authored"    sentinel gone AND OutcomeGuard.reason(intent_dir, disposition) is nil
+  #                 for EITHER "delivered" or "abandoned" (BLOCKING 3 fix: a fully-authored
+  #                 abandoned outcome.md is authored too; checking "delivered" only used to
+  #                 misreport it as "scaffolded, not authored" and point a resuming session
+  #                 back into Exec)
+  #   "scaffolded"  sentinel gone AND OutcomeGuard.reason(...) returns a reason string for
+  #                 BOTH dispositions
+  # OutcomeGuard.reason is the single existing definition of "is outcome.md real for this
+  # close"; this never re-derives that definition.
+  def classify_outcome(intent_dir)
+    outcome_path = File.join(intent_dir, "outcome.md")
+    return ["not_started", nil] unless Bridge.stage_file_present?(outcome_path)
+
+    delivered_reason = OutcomeGuard.reason(intent_dir, "delivered")
+    return ["authored", nil] if delivered_reason.nil?
+
+    abandoned_reason = OutcomeGuard.reason(intent_dir, "abandoned")
+    return ["authored", nil] if abandoned_reason.nil?
+
+    # Neither disposition's guard passed: report the "delivered" reason, since it is the
+    # more common close path and OutcomeGuard.reason's message already names whatever
+    # disposition is actually recorded in the frontmatter (or that the file is missing or
+    # still the scaffold placeholder), so it stays informative either way.
+    ["scaffolded", delivered_reason]
+  end
+
+  def settled_text(header)
+    return "no" unless header[:settled]
+    header[:settled_reason] ? "yes (#{header[:settled_reason]})" : "yes"
+  end
+
+  # Build the resume-station report. Every value comes from already-committed files
+  # (Bridge.stage_file_present?, Bridge.has_real_action?, SpecHeader, OutcomeGuard) or from
+  # `data`, the Hash Bridge.arm_* itself returned. No model inference, no free text beyond
+  # the fixed shape below.
+  def build_report(intent_dir:, mode:, data:)
+    spec_path = File.join(intent_dir, "spec.md")
+    plan_path = File.join(intent_dir, "plan.md")
+    checklist_path = File.join(intent_dir, "checklist.md")
+
+    spec_delivered = Bridge.stage_file_present?(spec_path)
+    plan_delivered = Bridge.stage_file_present?(plan_path)
+    checklist_delivered = Bridge.stage_file_present?(checklist_path)
+    has_action = Bridge.has_real_action?(intent_dir)
+    how_triple = plan_delivered && checklist_delivered && has_action
+
+    outcome_state, outcome_reason = classify_outcome(intent_dir)
+
+    resume_at =
+      if !spec_delivered
+        "Why"
+      elsif !how_triple
+        "How"
+      elsif outcome_state != "authored"
+        "Exec"
+      else
+        "Done"
+      end
+
+    header = SpecHeader.parse_file(spec_path)
+    tier = header[:tier] || "unknown"
+
+    worktree_code = data.dig("worktree", "code")
+    worktree_line = Bridge.blank?(worktree_code) ? "not provisioned" : worktree_code
+
+    outcome_line =
+      case outcome_state
+      when "authored" then "authored"
+      when "scaffolded" then "scaffolded, not authored (#{outcome_reason})"
+      else "not started"
+      end
+
+    lines = []
+    lines << "start-intent: #{File.basename(intent_dir)}"
+    lines << "  mode:        #{mode}"
+    lines << "  session:     #{data['session']}"
+    lines << "  lock:        held by #{data.dig('lock', 'owner_session')} (ours)"
+    lines << "  worktree:    #{worktree_line}"
+    lines << "  tier:        #{tier}"
+    lines << "  settled:     #{settled_text(header)}"
+    lines << "  spec.md:     #{spec_delivered ? 'delivered' : 'not started'}"
+    lines << "  plan.md:     #{plan_delivered ? 'delivered' : 'not started'}"
+    lines << "  checklist.md: #{checklist_delivered ? 'delivered' : 'not started'}"
+    lines << "  actions/:    #{real_action_count(intent_dir)} real action file(s)"
+    lines << "  outcome.md:  #{outcome_line}"
+    lines << "  resume at:   #{resume_at}"
+    lines.join("\n")
+  end
+
+  # --- entry point --------------------------------------------------------------------
+
+  def usage_result(message)
+    { exit_code: EXIT_USAGE, stderr: [message], stdout: [] }
+  end
+
+  def deny_result(code, message)
+    { exit_code: code, stderr: [message], stdout: [] }
+  end
+
+  def run(store:, id:, mode:, session:, env_session:, harness:, thread:, armer: default_armer)
+    return usage_result("--store is required") if Bridge.blank?(store)
+    return usage_result("--id is required") if Bridge.blank?(id)
+    return usage_result("--mode is required") if Bridge.blank?(mode)
+    unless %w[auto guided].include?(mode)
+      return usage_result("--mode must be one of auto, guided (got #{mode.inspect})")
+    end
+
+    store_abs = ScaffoldIntent.expand(store)
+    return usage_result("store dir does not exist: #{store_abs}") unless Dir.exist?(store_abs)
+
+    intent_dir, resolve_err = ScaffoldIntent.resolve_intent_dir(store_abs, id)
+    return usage_result(resolve_err) if intent_dir.nil?
+
+    name = resolve_name(intent_dir)
+    key_session = resolve_session(session, env_session)
+
+    verdict, lock = preflight_verdict(intent_dir, key_session)
+    case verdict
+    when :corrupt
+      return deny_result(EXIT_UNRESOLVED, corrupt_message(intent_dir))
+    when :no_session
+      return deny_result(EXIT_UNRESOLVED, no_session_message(intent_dir))
+    when :held
+      return deny_result(EXIT_HELD, held_message(intent_dir, lock, harness: harness))
+    end
+    # :proceed and :stale both fall through to arming; Bridge.arm_* arbitrates :stale
+    # itself (and raises Bridge::LockHeldError with the reclaim hint) via its own
+    # up-to-date Lock.acquire call.
+
+    data =
+      begin
+        armer.call(mode, session: key_session, intent_id: id, intent_dir: intent_dir,
+                   store: store_abs, name: name, harness: harness, agent: nil, model: nil,
+                   thread: thread)
+      rescue Bridge::LockHeldError => e
+        return deny_result(EXIT_HELD, e.message)
+      end
+
+    report = build_report(intent_dir: intent_dir, mode: mode, data: data)
+    { exit_code: EXIT_OK, stderr: [], stdout: [report] }
+  end
+end

package/scripts/lib/verify_intent.rb

@@ -0,0 +1,262 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "worktree"
+require_relative "scaffold_intent"
+
+# VerifyIntent - all logic for `scripts/verify-intent` (intent 213). Bundles the checks that
+# need no project-specific knowledge into one verdict: the per-intent doctor scan
+# (`Doctor#run_intent_check`), a net-new added-line em-dash diff guard (the first standing
+# implementation of this check; the only prior automated em-dash check,
+# `test/skill_command_lint_test.rb`, asserts against two FIXED file sets and cannot scan a
+# diff), a diffstat, and an optional caller-supplied `--suite` command folded into the same
+# verdict.
+#
+# Repo resolution and base-branch detection are NOT re-implemented here: `resolve_repo_dir`,
+# `detect_base_branch`, and `diffstat` are `ScaffoldIntent`'s own shared git seam helpers
+# (built for `scripts/scaffold-intent`, intent 213 ACTION_2); this module calls them so
+# there is exactly one implementation of each in the repo.
+#
+# Pure and dependency-injected: never calls `exit` or `abort`, never reads `ARGV`. The public
+# entry point (`run`) returns a verdict hash; `scripts/verify-intent` maps it to stdout lines
+# plus an exit code. Seams: `git_runner:` (defaults to `Worktree::ShellRunner.new`),
+# `doctor:` (a lambda, defaults to a real `Doctor#run_intent_check` call), `suite_runner:` (a
+# lambda, defaults to a real subprocess with `RUBYOPT` cleared).
+module VerifyIntent
+  module_function
+
+  # Built from its codepoint, never typed as a literal byte, so this file's own source stays
+  # free of the character it is written to detect (matching scripts/end-intent's own
+  # EM_DASH constant, built the same way).
+  EM_DASH = "\u2014"
+
+  EXIT_OK = 0
+  EXIT_USAGE = 1
+  EXIT_DOCTOR = 2
+  EXIT_EMDASH = 3
+  EXIT_SUITE = 4
+
+  # --- entry point ---------------------------------------------------------------
+
+  def run(store:, id:, base: nil, suite: nil, home: Dir.home,
+          git_runner: Worktree::ShellRunner.new, doctor: default_doctor, suite_runner: default_suite_runner)
+    return usage_result("--store is required") if Worktree.blank?(store)
+    return usage_result("--id is required") if Worktree.blank?(id)
+
+    intent_dir, resolve_err = ScaffoldIntent.resolve_intent_dir(store, id)
+    return usage_result(resolve_err) if intent_dir.nil?
+
+    gate_home, scope = resolve_plastic_home_and_scope(store)
+
+    lines = []
+    checks = {}
+    codes = []
+
+    doctor_lines, doctor_code, doctor_check = run_doctor_check(home: gate_home, scope: scope, id: id, doctor: doctor)
+    lines.concat(doctor_lines)
+    checks[:doctor] = doctor_check
+    codes << doctor_code if doctor_code
+
+    repo = ScaffoldIntent.resolve_repo_dir(store: store, id: id, intent_dir: intent_dir, home: home, runner: git_runner)
+    base_ref = base
+    base_ref ||= repo ? ScaffoldIntent.detect_base_branch(repo, runner: git_runner) : nil
+
+    emdash_lines, emdash_code, emdash_check = run_emdash_check(repo: repo, base: base_ref, git_runner: git_runner)
+    lines.concat(emdash_lines)
+    checks[:emdash] = emdash_check
+    codes << emdash_code if emdash_code
+
+    diffstat_lines, diffstat_check = run_diffstat_check(repo: repo, base: base_ref, git_runner: git_runner)
+    lines.concat(diffstat_lines)
+    checks[:diffstat] = diffstat_check
+
+    if Worktree.blank?(suite)
+      checks[:suite] = { status: "skipped" }
+    else
+      suite_lines, suite_code, suite_check = run_suite_check(suite: suite, repo: repo, suite_runner: suite_runner)
+      lines.concat(suite_lines)
+      checks[:suite] = suite_check
+      codes << suite_code if suite_code
+    end
+
+    { exit_code: codes.compact.min || EXIT_OK, lines: lines, checks: checks }
+  end
+
+  def usage_result(message)
+    { exit_code: EXIT_USAGE, lines: ["verify-intent: #{message}"], checks: {} }
+  end
+
+  # --- store/scope resolution (mirrors scripts/end-intent:161-170) ---------------
+
+  # `store` is `<plastic_home>/store` or `<plastic_home>/projects/<slug>/store`. The two
+  # shapes are told apart by whether store's grandparent is literally named "projects" (the
+  # StoreDiscovery convention), never by hardcoding ".plastic" as a name.
+  def resolve_plastic_home_and_scope(store)
+    parent = File.dirname(store)
+    grandparent = File.dirname(parent)
+    if File.basename(grandparent) == "projects"
+      [File.dirname(grandparent), "project:#{File.basename(parent)}"]
+    else
+      [parent, "global"]
+    end
+  end
+
+  # --- check 1: doctor, scoped to the intent --------------------------------------
+
+  def default_doctor
+    lambda do |home:, scope:, id:|
+      require_relative "../doctor"
+      Doctor.new(plastic_home: home, runner: Doctor.default_runner).run_intent_check(id, store: scope)
+    end
+  end
+
+  # Fail-open on any crash (a broken diagnostic must never wedge a verify): the check is
+  # skipped, not failed.
+  def run_doctor_check(home:, scope:, id:, doctor:)
+    verdict = doctor.call(home: home, scope: scope, id: id)
+    case verdict[:status]
+    when "fail"
+      failing = Array(verdict[:checks]).select { |c| c[:status] == "fail" }
+      lines = failing.map { |c| "doctor: FAIL #{c[:name]}: #{c[:message]}" }
+      lines = ["doctor: FAIL"] if lines.empty?
+      [lines, EXIT_DOCTOR, { status: "fail", verdict: verdict }]
+    when "warn"
+      warning = Array(verdict[:checks]).select { |c| c[:status] == "warn" }
+      lines = warning.map { |c| "doctor: WARN #{c[:name]}: #{c[:message]}" }
+      lines = ["doctor: WARN"] if lines.empty?
+      [lines, nil, { status: "warn", verdict: verdict }]
+    else
+      [["doctor: pass"], nil, { status: "pass", verdict: verdict }]
+    end
+  rescue StandardError => e
+    [["doctor crashed (#{e.message}); proceeding without it"], nil, { status: "crashed", error: e.message }]
+  end
+
+  # --- check 2: the added-line em-dash diff guard (net-new, D9) -------------------
+
+  # Store and intent files are exempt from the no-em-dash rule (AGENTS.md states this
+  # explicitly), and INDEX.md is REQUIRED to carry a real em dash on write
+  # (scripts/end-intent:82-88). No per-file allow-list beyond these three shapes.
+  def exempt_path?(path)
+    return true if path.nil?
+    return true if path.start_with?("store/")
+    return true if path.split("/").include?(".plastic")
+    return true if path == "INDEX.md" || path.end_with?("/INDEX.md")
+    return true if path.start_with?("test/fixtures/")
+
+    false
+  end
+
+  HUNK_HEADER_RE = /\A@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/
+
+  # Scan ONLY the added lines of a unified diff (never a removed line, never a context
+  # line, never the `+++ ` file header line itself). An added line starts with exactly one
+  # `+` and is not the file header; per the spec this is decided with
+  # `l.start_with?("+") && !l.start_with?("+++")`. Tracks the current file from the most
+  # recent `+++ b/<path>` header and the current new-file line number from the most recent
+  # `@@ -a,b +c,d @@` hunk header, incrementing on every context or added line (never on a
+  # removed line, which does not exist in the new file).
+  def em_dash_violations(diff_text)
+    violations = []
+    current_file = nil
+    current_line = nil
+    exempt = false
+
+    diff_text.to_s.each_line do |line|
+      if line.start_with?("+++")
+        current_file = line.sub(/\A\+\+\+\s*/, "").strip.sub(%r{\Ab/}, "")
+        exempt = exempt_path?(current_file)
+        next
+      end
+
+      if (m = line.match(HUNK_HEADER_RE))
+        current_line = m[1].to_i
+        next
+      end
+
+      if line.start_with?("+")
+        text = line[1..].to_s.chomp
+        violations << { file: current_file, line: current_line, text: text } if !exempt && text.include?(EM_DASH)
+        current_line += 1 if current_line
+      elsif line.start_with?("-")
+        # A removed line does not exist in the new file: never scanned, never counted.
+      elsif line.start_with?(" ")
+        current_line += 1 if current_line
+      end
+    end
+
+    violations
+  end
+
+  def run_emdash_check(repo:, base:, git_runner:)
+    if repo.nil?
+      return [["em-dash guard skipped: no repo could be resolved for this intent"], nil,
+              { status: "skipped", reason: "no repo" }]
+    end
+    if base.nil?
+      return [["em-dash guard skipped: no base branch could be detected (no origin/HEAD, main, or master)"], nil,
+              { status: "skipped", reason: "no base" }]
+    end
+
+    res = git_runner.run("-C", repo, "diff", "#{base}...HEAD")
+    unless res.success?
+      reason = res.stderr.to_s.strip
+      return [["em-dash guard skipped: #{reason}"], nil, { status: "skipped", reason: reason }]
+    end
+
+    violations = em_dash_violations(res.stdout)
+    if violations.empty?
+      [["em-dash guard: pass (0 violations)"], nil, { status: "pass", violations: [] }]
+    else
+      lines = ["em-dash guard: #{violations.size} violation(s) found"]
+      lines.concat(violations.map { |v| "#{v[:file]}:#{v[:line]}: #{v[:text]}" })
+      [lines, EXIT_EMDASH, { status: "fail", violations: violations }]
+    end
+  end
+
+  # --- check 3: the diffstat -------------------------------------------------------
+
+  def run_diffstat_check(repo:, base:, git_runner:)
+    if repo.nil?
+      return [["diffstat unavailable: no repo could be resolved for this intent"], { status: "skipped" }]
+    end
+    if base.nil?
+      return [["diffstat unavailable: no base branch could be detected (no origin/HEAD, main, or master)"],
+              { status: "skipped" }]
+    end
+
+    stat, err = ScaffoldIntent.diffstat(repo, base, runner: git_runner)
+    if stat.nil?
+      [["diffstat unavailable: #{err}"], { status: "skipped" }]
+    else
+      lines = ["diffstat against #{base}:"]
+      lines.concat(stat.each_line.map(&:chomp))
+      [lines, { status: "pass", stat: stat }]
+    end
+  end
+
+  # --- check 4: the optional suite --------------------------------------------------
+
+  # The supplied command is very likely a ruby command, so it is spawned with RUBYOPT
+  # cleared, matching the pattern at scripts/maintenance-run:133.
+  def default_suite_runner
+    lambda do |command, dir|
+      require "open3"
+      out, status = Open3.capture2e({ "RUBYOPT" => nil }, command, chdir: dir || Dir.pwd)
+      [out, status.exitstatus]
+    end
+  end
+
+  def run_suite_check(suite:, repo:, suite_runner:)
+    output, status = suite_runner.call(suite, repo)
+    lines = ["suite: #{suite}"]
+    lines.concat(output.to_s.each_line.map(&:chomp))
+    lines << "suite: exit #{status}"
+
+    if status.to_i.zero?
+      [lines, nil, { status: "pass", exit_status: status }]
+    else
+      [lines, EXIT_SUITE, { status: "fail", exit_status: status }]
+    end
+  end
+end

package/scripts/lib/worktree.rb

@@ -166,7 +166,21 @@ module Worktree
     # fails open on provisioned: false (non-git / global-only).
     block["provisioned"] = code_ok
 
-    bridge_data["worktree"] = block
+    # Intent 230: only OVERWRITE the worktree block when the code worktree was
+    # actually added. On failure, keep a pointer the caller already had rather
+    # than erasing it -- clearing it is what sent code edits into the shared
+    # checkout. A pointer whose directory is gone is worse than none, so it is
+    # replaced by the fresh unprovisioned block; the guard must not fail harder
+    # than the bug it guards.
+    if code_ok
+      bridge_data["worktree"] = block
+    else
+      existing = bridge_data["worktree"]
+      keep = existing.is_a?(Hash) && !blank?(existing["code"]) &&
+             Dir.exist?(existing["code"].to_s)
+      bridge_data["worktree"] = block unless keep
+    end
+
     bridge_data
   end
 

package/scripts/link-suggest

@@ -195,7 +195,7 @@ module LinkSuggestCLI
   def qmd_search_ids(query, nodes)
     return [] if query.to_s.strip.empty?
 
-    out = `ruby #{File.join(Dir.home, ".plastic", "scripts", "qmd-sync")} search #{shell_quote(query)} 2>/dev/null`
+    out = `env -u RUBYOPT ruby #{File.join(Dir.home, ".plastic", "scripts", "qmd-sync")} search #{shell_quote(query)} 2>/dev/null`
     return [] if out.nil? || out.empty?
 
     out.scan(/\b([0-9]+[a-z0-9]*)\b/).flatten.uniq.select { |id| nodes.key?(id) }

package/scripts/maintenance-run

@@ -130,7 +130,7 @@ def run_project_links(home, intent, store, apply)
   base_args += ["--store", store] if store
 
   unless apply
-    system(RbConfig.ruby, tool_path, *base_args, "--dry-run")
+    system({"RUBYOPT" => nil}, RbConfig.ruby, tool_path, *base_args, "--dry-run")
     exit($?.exitstatus)
   end
 
@@ -139,7 +139,7 @@ def run_project_links(home, intent, store, apply)
       repo_dir: home, branch_name: "maintenance/project-links-#{intent}-#{stamp}",
       commit_message: "chore: maintenance - project-links --intent #{intent}"
     ) do
-      ok = system(RbConfig.ruby, tool_path, *base_args)
+      ok = system({"RUBYOPT" => nil}, RbConfig.ruby, tool_path, *base_args)
       raise "project-links failed for #{intent}" unless ok
     end
   rescue MaintenanceGit::DirtyWorkingTree, MaintenanceGit::NotAGitRepo => e
@@ -171,7 +171,7 @@ def run_rebuild_graph(home, apply)
       repo_dir: home, branch_name: "maintenance/rebuild-graph-#{stamp}",
       commit_message: "chore: maintenance - rebuild-graph"
     ) do
-      ok = system(RbConfig.ruby, tool_path, "--plastic-home", home)
+      ok = system({"RUBYOPT" => nil}, RbConfig.ruby, tool_path, "--plastic-home", home)
       raise "rebuild-graph failed" unless ok
     end
   rescue MaintenanceGit::DirtyWorkingTree, MaintenanceGit::NotAGitRepo => e
@@ -200,7 +200,7 @@ def run_restore_intent_v1(home, id, at, store, apply, skip_links)
   args << "--skip-links" if skip_links
 
   unless apply
-    system(RbConfig.ruby, *args)
+    system({"RUBYOPT" => nil}, RbConfig.ruby, *args)
     exit($?.exitstatus)
   end
 
@@ -209,7 +209,7 @@ def run_restore_intent_v1(home, id, at, store, apply, skip_links)
       repo_dir: home, branch_name: "maintenance/restore-intent-v1-#{id}-#{stamp}",
       commit_message: "chore: maintenance - restore-intent-v1 #{id}"
     ) do
-      ok = system(RbConfig.ruby, *args, "--apply")
+      ok = system({"RUBYOPT" => nil}, RbConfig.ruby, *args, "--apply")
       raise "restore-intent-v1 failed for #{id}" unless ok
     end
   rescue MaintenanceGit::DirtyWorkingTree, MaintenanceGit::NotAGitRepo => e

package/scripts/migrate-to-global

@@ -44,7 +44,7 @@ fi
 
 # Rewrite relative links to wikilinks
 echo "  Rewriting links to [[ID]] format..."
-ruby <<'RUBY'
+env -u RUBYOPT ruby <<'RUBY'
   # Find intent files (named {ID}.md, the primary file in each intent directory)
   Dir.glob(File.expand_path("~/.plastic/store/*/")).each do |dir|
     id = File.basename(dir).split("--").first
@@ -68,7 +68,7 @@ RUBY
 # Register project in projects.yml
 echo "  Registering project..."
 REMOTE=$(cd "$PROJECT_PATH" && git remote get-url origin 2>/dev/null || echo "null")
-ruby -r yaml <<RUBY
+env -u RUBYOPT ruby -r yaml <<RUBY
   path = File.expand_path("$GLOBAL_ROOT/projects.yml")
   data = YAML.safe_load(File.read(path)) rescue {}
   data["projects"] ||= {}

package/scripts/restore-intent-v1

@@ -271,7 +271,7 @@ class RestoreIntentV1CLI
 
   def reproject_links
     project_links = File.expand_path("project-links", __dir__)
-    system(RbConfig.ruby, project_links, "--plastic-home", plastic_home)
+    system({"RUBYOPT" => nil}, RbConfig.ruby, project_links, "--plastic-home", plastic_home)
     return if $?.success?
 
     warn "restore-intent-v1: ## Links may now be stale (project-links reprojection failed). " \