@zalom/plastic 1.0.0-beta.9 → 1.0.1

package/scripts/new-intent

@@ -73,15 +73,28 @@ def default_templates_dir
 end
 
 def render_tokens(text, tokens)
-  tokens.reduce(text) { |acc, (k, v)| acc.gsub("{{#{k}}}", v.to_s) }
+  # Block-form gsub: a String replacement argument reinterprets backslash
+  # sequences (so a doubled backslash from escape_double_quoted_scalar
+  # collapses back to one); the block form substitutes the value literally.
+  tokens.reduce(text) { |acc, (k, v)| acc.gsub("{{#{k}}}") { v.to_s } }
+end
+
+# Escape the characters that would break a double-quoted YAML scalar: backslash
+# first, so a real backslash in the input isn't re-escaped by the quote step,
+# then the double quote itself. Used only for the frontmatter-bound INTENT
+# token; the body's DESCRIPTION copy stays raw (markdown prose, not a YAML
+# scalar) so escaping it would corrupt what the user actually typed.
+def escape_double_quoted_scalar(value)
+  value.to_s.gsub("\\") { "\\\\" }.gsub('"') { '\"' }
 end
 
 # Add an id to a source intent's frontmatter `chain` array, idempotently (I1
 # reciprocity: `child in parent.sources` => `parent.chain` gains `child`). A
-# targeted edit of the `chain:` line only; the body (including `## Links`) is
+# targeted edit that preserves every existing entry and appends the new id in
+# the SAME on-disk YAML style (flow `chain: [...]` or block `chain:` + indented
+# `- "id"` lines) the target already uses; the body (including `## Links`) is
 # preserved byte-for-byte and no other frontmatter key is touched, so the file
-# stays born-complete. Renders the array in flow style (`["a", "b"]`) to match
-# templates/intent.md. No-op when the id is already present.
+# stays born-complete. No-op when the id is already present.
 def add_to_chain(file_path, new_id)
   return unless File.exist?(file_path)
   content = File.read(file_path)
@@ -91,21 +104,41 @@ def add_to_chain(file_path, new_id)
   return unless parts.length >= 3
 
   fm = parts[1]
-  chain_line = fm.lines.find { |l| l.match?(/\A\s*chain\s*:/) }
-  return unless chain_line
+  lines = fm.lines
+  chain_idx = lines.index { |l| l.match?(/\A\s*chain\s*:/) }
+  return unless chain_idx
+
+  flow_match = lines[chain_idx].match(/\A\s*chain\s*:\s*\[(.*?)\]\s*\z/m)
+
+  if flow_match
+    ids = flow_match[1].scan(/"([^"]*)"|'([^']*)'/).flatten.compact
+    return if ids.include?(new_id)
+
+    ids << new_id
+    lines[chain_idx] = "chain: [#{ids.map { |i| "\"#{i}\"" }.join(", ")}]\n"
+  else
+    entry_re = /\A(\s*-\s*)(?:"([^"]*)"|'([^']*)'|(\S+))\s*\z/
+    entry_lines = []
+    j = chain_idx + 1
+    while j < lines.length && lines[j].match?(entry_re)
+      entry_lines << lines[j]
+      j += 1
+    end
+
+    ids = entry_lines.map { |l| (m = l.match(entry_re)) && (m[2] || m[3] || m[4]) }
+    return if ids.include?(new_id)
 
-  existing = fm.match(/\bchain\s*:\s*\[(.*?)\]/m)
-  ids =
-    if existing
-      existing[1].scan(/"([^"]*)"|'([^']*)'/).flatten.compact
+    if entry_lines.empty?
+      prefix, quote = "  - ", "\""
     else
-      []
+      m = entry_lines.last.match(entry_re)
+      prefix = m[1]
+      quote = m[2] ? "\"" : (m[3] ? "'" : "")
     end
-  return if ids.include?(new_id)
+    lines.insert(chain_idx + 1 + entry_lines.length, "#{prefix}#{quote}#{new_id}#{quote}\n")
+  end
 
-  ids << new_id
-  rendered = "chain: [#{ids.map { |i| "\"#{i}\"" }.join(", ")}]"
-  new_fm = fm.sub(/^\s*chain\s*:.*$/, rendered)
+  new_fm = lines.join
   File.write(file_path, ["", new_fm, parts[2]].join("---"))
 end
 
@@ -260,7 +293,7 @@ def main(argv)
   intent_template = File.read(File.join(templates, "intent.md"))
   intent_body = render_tokens(intent_template, {
     "ID" => id,
-    "INTENT" => opts[:intent],
+    "INTENT" => escape_double_quoted_scalar(opts[:intent]),
     "SOURCES" => sources_str,
     "DATE" => Date.today.iso8601,
     "AUTHOR" => opts[:author],
@@ -311,7 +344,15 @@ def main(argv)
     File.write(File.join(intent_dir, name), "#{Bridge::PLACEHOLDER_SENTINEL}\n#{body}")
   end
 
-  # 6. Self-validate (frontmatter + sanctioned sections).
+  # 6. Stamp the born savepoint line (intent 81). The first ledger line is the
+  # `What` bookend, written deterministically at creation rather than relying on
+  # a PostToolUse gate firing on the intent-file write (which is missed in some
+  # sessions / harnesses). The intent file is never a sentinel placeholder, so
+  # append_savepoint records `What  {id}--{slug}.md`. Idempotent: a later gate
+  # fire adds nothing.
+  Bridge.append_savepoint(intent_dir, intent_file)
+
+  # 7. Self-validate (frontmatter + sanctioned sections).
   result = IntentValidator.validate(intent_dir)
   unless result[:ok]
     warn "new-intent: scaffolded intent is NOT born complete:"

package/scripts/plastic-lock

@@ -0,0 +1,164 @@
+#!/usr/bin/env ruby
+# 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).
+#
+# Usage: plastic-lock <status|fix|release|reclaim|delegate|claim|release-claim>
+#          [--intent-dir DIR] [--session SID] [--delegate SID] [--artifact NAME]
+#
+# Verbs:
+#   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)
+#   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);
+#                 rejected (exit 1) while a fresh claim is held by anyone,
+#                 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).
+
+require "json"
+require_relative "lib/bridge"
+require_relative "lib/lock"
+
+def usage!
+  warn "usage: plastic-lock <status|fix|release|reclaim|delegate|claim|release-claim> " \
+       "[--intent-dir DIR] [--session SID] [--delegate SID] [--artifact NAME]"
+  exit 1
+end
+
+verb = ARGV.shift
+usage! unless %w[status fix release reclaim delegate claim release-claim].include?(verb)
+
+opts = {}
+until ARGV.empty?
+  case (flag = ARGV.shift)
+  when "--intent-dir" then opts[:dir] = ARGV.shift
+  when "--session" then opts[:session] = ARGV.shift
+  when "--delegate" then opts[:delegate] = ARGV.shift
+  when "--artifact" then opts[:artifact] = ARGV.shift
+  else
+    warn "unknown flag #{flag}"
+    usage!
+  end
+end
+
+session = opts[:session]
+session = ENV["CLAUDE_CODE_SESSION_ID"] if session.nil? || session.strip.empty?
+
+dir = opts[:dir]
+if dir.nil? || dir.strip.empty?
+  bridge = Bridge.discover_bridge(session: session, cwd: Dir.pwd)
+  dir = Bridge.bridge_intent_dir(bridge)
+end
+if dir.nil?
+  warn "plastic-lock: no intent resolved; pass --intent-dir <intent dir>"
+  exit 1
+end
+dir = File.expand_path(dir)
+
+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)
+
+case verb
+when "status"
+  lock = Lock.read(dir)
+  bridge = Bridge.read(key, intent_id: intent_id)
+  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,
+    "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)
+  puts JSON.pretty_generate(report)
+  unless report["status"] == "repaired"
+    warn "plastic-lock: #{report['status']} by #{report['owner']}" \
+         "#{report['hint'] ? " (#{report['hint']})" : ''}"
+    exit 1
+  end
+when "release"
+  result = Lock.release(dir, session: key)
+  if result == :not_owner
+    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
+  puts "released (#{result})"
+when "reclaim"
+  status, lock_data = Lock.takeover(dir, session: key)
+  if status == :fresh
+    warn "plastic-lock: lock is FRESH and held by #{lock_data['owner_session']}; " \
+         "back off (no silent reclaim)"
+    exit 1
+  end
+  report = Bridge.repair_lock(key, intent_id: intent_id, intent_dir: dir,
+                              store: store, name: name)
+  puts JSON.pretty_generate(report)
+when "delegate"
+  usage! if opts[:delegate].nil?
+  ok = Lock.add_delegate(dir, delegate: opts[:delegate], session: key)
+  unless ok
+    warn "plastic-lock: only the lock owner may delegate; run plastic-lock status"
+    exit 1
+  end
+  puts "delegated #{opts[:delegate]} under #{key}"
+when "claim"
+  usage! if opts[:artifact].nil?
+  status, data = Claim.acquire_claim(dir, opts[:artifact], session: key,
+                                     delegate: opts[:delegate])
+  case status
+  when :acquired
+    puts "claimed #{opts[:artifact]} under #{key}"
+  when :held
+    warn "plastic-lock: #{opts[:artifact]} is claimed by " \
+         "#{data['owner_session']} since #{data['acquired_at']}; back off"
+    exit 1
+  when :stale
+    old = data && data["owner_session"]
+    Claim.release_claim(dir, opts[:artifact], session: key, force: true)
+    status2, = Claim.acquire_claim(dir, opts[:artifact], session: key,
+                                   delegate: opts[:delegate])
+    if status2 == :acquired
+      warn "plastic-lock: took over stale claim on #{opts[:artifact]} from #{old}"
+      puts "claimed #{opts[:artifact]} under #{key}"
+    else
+      warn "plastic-lock: could not take over #{opts[:artifact]} (#{status2})"
+      exit 1
+    end
+  when :corrupt
+    Claim.release_claim(dir, opts[:artifact], session: key, force: true)
+    Claim.acquire_claim(dir, opts[:artifact], session: key, delegate: opts[:delegate])
+    puts "claimed #{opts[:artifact]} under #{key} (repaired corrupt claim)"
+  end
+when "release-claim"
+  usage! if opts[:artifact].nil?
+  result = Claim.release_claim(dir, opts[:artifact], session: key)
+  if result == :not_owner
+    warn "plastic-lock: not the claim owner; run plastic-lock status"
+    exit 1
+  end
+  puts "released-claim #{opts[:artifact]} (#{result})"
+end

package/scripts/read-config

@@ -9,6 +9,7 @@
 
 require "yaml"
 require "json"
+require_relative "lib/agent_models"
 
 DEFAULTS = {
   "version" => 3,
@@ -23,6 +24,9 @@ DEFAULTS = {
     "type" => "claude-code",
     "parallel_mode" => "linear"
   },
+  "agents" => {
+    "models" => AgentModels::TIER_DEFAULTS
+  },
   "architect" => {
     "style" => nil
   }

package/scripts/spawn-preamble

@@ -23,6 +23,7 @@
 # Exit codes: 0 (preamble emitted), 2 (usage).
 
 require_relative "lib/bridge"
+require_relative "lib/worktree"
 
 # Verbatim honoring instruction. Kept as one constant so the contract doc and the
 # test assert against the exact same string.
@@ -31,6 +32,16 @@ HONOR_INSTRUCTION =
   "Emit VALID lifecycle artifacts; do not hallucinate intents or stages. " \
   "Your primary output is valid lifecycle artifacts; you close with a structured report about them."
 
+# Verbatim cd-fallback instruction (intent 152). The harness's own EnterWorktree
+# tool assumes cwd IS the repo root, which fails when a dispatched agent's
+# session launches from a directory that is not itself a git repo (the normal
+# shape for a background job): it cannot discover the nested project repo
+# underneath it. Kept as one constant so the doc and the test assert against
+# the exact same string.
+WORKTREE_FALLBACK_INSTRUCTION =
+  "If EnterWorktree fails to discover the nested repo from a non-repo launch " \
+  "directory, cd directly to the code worktree path above before editing project code."
+
 # Verbatim completion-report contract (intent 74). Kept as one constant so the
 # contract doc (skills/auto/references/agent-report-contract.md), the role prompts,
 # and the test assert against the exact same string. SINGLE SOURCE OF TRUTH for the
@@ -41,10 +52,18 @@ REPORT_CONTRACT =
   "FINAL MESSAGE (your return value), not a side-channel file. Do not go idle or " \
   "finish silently. The report carries a common envelope: role, intent id, stage, " \
   "status (delivered or blocked), artifacts written, verification or tests run, " \
-  "checklist deltas, deviations from spec, and blockers or handoff notes; plus a " \
+  "checklist deltas, deviations from spec, blockers or handoff notes, and an " \
+  "insights field carrying 0..N durable nuggets (what I discovered worth keeping, " \
+  "the most interesting residue of this turn; none if there were none); plus a " \
   "role-specific payload that fulfils your place in the What, Why, How, Exec cycle " \
-  "(for example the planner explains the plan back to the orchestrator). See " \
-  "skills/auto/references/agent-report-contract.md for the per-role format."
+  "(for example the planner explains the plan back to the orchestrator). Populate " \
+  "the insights field even when you cannot write the intent file yourself: a " \
+  "background or dispatched agent carries each nugget home in the report and the " \
+  "orchestrator persists it via scripts/insight-append, so an insight never " \
+  "depends on the discovering session's file-write access. Keep the report " \
+  "prose-stripped: the envelope and payload only, no greeting, no preamble, " \
+  "no end-recap, no restating of the task; reasoning stays in the thinking channel. " \
+  "See skills/auto/references/agent-report-contract.md for the per-role format."
 
 def parse_args(argv)
   role = nil
@@ -115,7 +134,8 @@ end
 intent_dir = File.expand_path(intent_dir_arg)
 
 fm = frontmatter_for(intent_dir)
-id = fm["id"].to_s.strip
+raw_id = fm["id"].to_s.strip
+id = raw_id
 intent_name = fm["intent"].to_s.strip
 id = "(unknown)" if id.empty?
 intent_name = "(unknown)" if intent_name.empty?
@@ -123,12 +143,24 @@ intent_name = "(unknown)" if intent_name.empty?
 stage = current_stage(intent_dir)
 cycle = role || step || stage
 
+# Already-provisioned code worktree path (intent 152), resolved purely from
+# filesystem/YAML state (no git shell-out): see Worktree.paths's own doc
+# comment. Fails open (no lines added) when unresolvable or not on disk.
+store_root = File.dirname(intent_dir)
+project_slug = Worktree.slug_for_store(store_root)
+intent_slug = Worktree.slug_from_dir(intent_dir)
+code_path = Worktree.paths(slug: project_slug, intent_id: raw_id, intent_slug: intent_slug)["code"]
+
 lines = []
 lines << "=== Plastic spawn preamble ==="
 lines << "Store: #{intent_dir}"
 lines << "Active intent: #{id} - #{intent_name}"
 lines << "Current stage: #{stage}"
 lines << "Cycle step / role: #{cycle}"
+if code_path && Dir.exist?(code_path)
+  lines << "Code worktree: #{code_path}"
+  lines << WORKTREE_FALLBACK_INSTRUCTION
+end
 lines << ""
 lines << HONOR_INSTRUCTION
 lines << ""

package/scripts/update.rb

@@ -53,18 +53,22 @@ class Update < InstallerCore
       end
       puts "\u{2b06}\u{fe0f}  Updating Plastic #{iv} \u{2192} #{res[:target]}"
       exit_code = perform_switch(res[:target], agent_args(argv))
-      run_post_update_doctor if exit_code == 0
+      run_post_update_doctor(full: argv.include?("--full-doctor")) if exit_code == 0
       exit_code
     end
   end
 
-  # Run the full doctor after a successful update and print a human-readable
-  # summary. Informational only: does not raise and does not affect the update's
-  # exit code. Accepts injected `doctor` and `out` for hermetic unit tests.
-  def run_post_update_doctor(doctor: nil, out: $stdout)
+  # Run doctor after a successful update and print a human-readable summary.
+  # Defaults to the fast core tier (agent registration + core files + manifest
+  # sync, binary pass|fail, no store walk) so a newcomer's first post-update
+  # run is not buried in convention warns they cannot act on. `full: true`
+  # (via `--full-doctor`) runs the complete store walk instead. Informational
+  # only: does not raise and does not affect the update's exit code. Accepts
+  # injected `doctor` and `out` for hermetic unit tests.
+  def run_post_update_doctor(doctor: nil, out: $stdout, full: false)
     doctor ||= Doctor.new
-    out.puts "\nRunning full doctor after update..."
-    result = doctor.run_checks("claude")
+    out.puts full ? "\nRunning full doctor after update..." : "\nRunning core doctor after update..."
+    result = full ? doctor.run_checks("claude") : doctor.run_core_checks("claude")
     s = result[:summary]
     out.puts "  Doctor status: #{result[:status]} " \
              "(pass: #{s[:pass]}, warn: #{s[:warn]}, fail: #{s[:fail]}, total: #{s[:total]})"
@@ -152,6 +156,11 @@ class Update < InstallerCore
       Agent options (default: --claude):
         --claude --codex --hermes --all
 
+      Post-update doctor:
+        By default, a successful update runs the fast core doctor sync (agent
+        registration, core files, manifest — binary pass|fail, no store walk).
+        --full-doctor   Run the full doctor (complete store walk) after updating.
+
       Behaviour:
         No flag advances to the next version on your current channel. Switching toward a
         more stable channel is frictionless; switching toward bleeding edge is confirmed.