@zalom/plastic 2.0.1 → 2.0.3

package/scripts/lib/cli/commands/auto_take.rb

@@ -1,30 +1,67 @@
 # frozen_string_literal: true
 
+require "json"
 require_relative "intent_command"
 
 # `plastic auto take` - arms the intent's delivery lock for this session
 # (`plastic-lock arm --intent-dir DIR --mode auto`, run through Legacy).
+# The lock records who took it: --harness, --agent, --model and --thread pass
+# through, and a Claude Code session names its harness when none is given.
+# plastic-lock answers in JSON, so this command renders it as a screen and
+# leaves the document to `--json`. A lock another session owns exits 3.
 module Plastic
   class CLI
     module Commands
       class AutoTake < IntentCommand
-        USAGE_LINE = "plastic auto take ID [--allow-inline] [--json]"
+        USAGE_LINE = "plastic auto take ID [--allow-inline] [--harness NAME] [--agent NAME] " \
+                     "[--model MODEL] [--thread ID] [--json]"
 
         SCRIPT = "plastic-lock"
         AFTER = "plastic auto brief ID"
         BECAUSE = "the preamble is the live state a taken intent is read from next"
+        PROVENANCE = %i[harness agent model thread].freeze
+
+        def call
+          return super if options[:json]
+
+          text, status = legacy.capture(SCRIPT, *script_arguments)
+          raise Failure, "#{SCRIPT} exited #{status}" unless status.zero?
+
+          screen(JSON.parse(text))
+          command, reason = after_run
+          @output.next_step(command, because: reason)
+        rescue JSON::ParserError
+          raise Failure, "#{SCRIPT} did not print a report"
+        end
 
         private
 
         def switches(parser)
           parser.on("--allow-inline") { @options[:allow_inline] = true }
+          PROVENANCE.each do |name|
+            parser.on("--#{name} VALUE") { |value| @options[name] = value }
+          end
         end
 
         def script_arguments
           args = ["arm", "--intent-dir", intent_dir, "--mode", "auto"]
+          provenance.each { |name, value| args.push("--#{name}", value) }
           args << "--allow-inline" if options[:allow_inline]
           args
         end
+
+        def provenance
+          given = PROVENANCE.to_h { |name| [name, options[name]] }
+          given[:harness] ||= "claude" if @env["CLAUDE_CODE_SESSION_ID"].to_s.strip != ""
+          given.compact
+        end
+
+        def screen(report)
+          worktree = report["worktree"] || {}
+          @output.row("intent", File.basename(report["intent_dir"].to_s))
+          @output.row("lock", "#{report["status"]} by #{report["session"]}, #{report["run_mode"]} mode")
+          @output.row("worktree", worktree["provisioned"] ? worktree["code"].to_s : "none")
+        end
       end
     end
   end

package/scripts/lib/cli/commands/doctor.rb

@@ -15,8 +15,8 @@ module Plastic
   class CLI
     module Commands
       class Doctor < InstallerVerb
-        USAGE_LINE = "plastic doctor [--core] [--store WHICH] [--json]"
-        FLAGS = %w[--core --store].freeze
+        USAGE_LINE = "plastic doctor [--core] [--agent claude|codex|hermes] [--store WHICH] [--json]"
+        FLAGS = %w[--core --agent --store].freeze
 
         SCRIPT = "doctor.rb"
         AFTER = "none"

package/scripts/lib/cli/commands/intent_command.rb

@@ -22,11 +22,16 @@ module Plastic
           status = legacy.run(self.class::SCRIPT, *script_arguments)
           raise Failure, "#{self.class::SCRIPT} exited #{status}" unless status.zero?
 
-          @output.next_step(self.class::AFTER.sub("ID", id.to_s), because: self.class::BECAUSE)
+          command, reason = after_run
+          @output.next_step(command, because: reason)
         end
 
         private
 
+        def after_run
+          [self.class::AFTER.sub("ID", id.to_s), self.class::BECAUSE]
+        end
+
         def id
           arguments.first
         end

package/scripts/lib/cli/commands/intent_end.rb

@@ -15,6 +15,15 @@ module Plastic
 
         REFUSAL_STATUS = 4
 
+        # end-intent's own refusals the agent can act on: the reason is theirs to
+        # fix, so they stay failures (exit 1), but each is named rather than
+        # surfaced as a bare exit code.
+        REFUSED = {
+          7 => "end-intent refused a hollow delivered close: write outcome.md's ## Delivered rows to match the action headings",
+          8 => "end-intent refused to deliver an untouched scaffold: do the work first, or close it with --abandoned",
+          9 => "end-intent refused a delivered close whose code is not merged: run the git merge it names in the repo, then run the close again"
+        }.freeze
+
         SUMMARY_GUIDANCE = [
           "a good summary is written for the reader deciding whether to merge, release, or accept",
           "delivered: what shipped, impact and risk first, in plain language, never the checklist",
@@ -28,9 +37,13 @@ module Plastic
 
           status = legacy.run("end-intent", *end_intent_arguments)
           raise Refusal, "end-intent needs the owner: the delivery lock is held" if status == REFUSAL_STATUS
-          raise Failure, "end-intent exited #{status}" unless status.zero?
+          raise Failure, REFUSED.fetch(status) { "end-intent exited #{status}" } unless status.zero?
 
-          @output.next_step("plastic status", because: "the intent moved out of Active")
+          if options[:dry_run]
+            @output.next_step("none", because: "the dry run wrote nothing and found nothing that would refuse the close")
+          else
+            @output.next_step("plastic status", because: "the intent is now closed")
+          end
         end
 
         private

package/scripts/lib/cli/commands/intent_step.rb

@@ -16,6 +16,7 @@ module Plastic
         SCRIPT = "runner"
         AFTER = "plastic intent step ID"
         BECAUSE = "call step again after each dispatched node returns"
+        COMPLETE = "every node in the graph has finished"
 
         def call
           intent_dir
@@ -49,11 +50,18 @@ module Plastic
             env_session: @env["CLAUDE_CODE_SESSION_ID"], store: scope.store, intent_id: id)
           return true if session
           raise Refusal, "intent #{id} is held by another session; inspect with plastic auto lock status #{id} --project #{scope.slug}" if Lock.read(intent_dir)
+          raise Refusal, "return not accepted: take intent #{id} with plastic auto take #{id} --project #{scope.slug} before submitting it" unless Array(options[:returns]).empty?
 
           @output.next_step("plastic auto take #{id}", because: "graph execution requires this session to take the delivery lock")
           false
         end
 
+        def after_run
+          return super unless RunnerCore.complete?(RunnerCore.context(intent_dir: intent_dir, home: File.dirname(scope.plastic_home)))
+
+          ["plastic intent verify #{id}", COMPLETE]
+        end
+
         def graph?
           File.exist?(File.join(intent_dir, "graph.md"))
         end

package/scripts/lib/cli/commands/project_links.rb

@@ -20,7 +20,11 @@ module Plastic
           status = legacy.run("project-links", "--plastic-home", scope.plastic_home, *dry_run_flag)
           raise Failure, "project-links exited #{status}" unless status.zero?
 
-          @output.next_step("plastic status", because: "the Links sections just rebuilt across every store")
+          if options[:dry_run]
+            @output.next_step("none", because: "the preview wrote no files")
+          else
+            @output.next_step("plastic status", because: "the Links sections just rebuilt across every store")
+          end
         end
 
         private

package/scripts/lib/cli/commands/project_new.rb

@@ -9,13 +9,18 @@ require_relative "../../store_provisioning"
 # `plastic project new` - registers a project in projects.yml, then provisions
 # and validates its store (`provision-project-store`, `validate-project`, run
 # through Legacy). The project directory must already exist; this command
-# never makes one, and a slug already registered is a Failure.
+# never makes one. A slug is lowercase letters, digits and hyphens, starting
+# with a letter or digit, and never `global`. A slug or a path already
+# registered is a Failure.
 module Plastic
   class CLI
     module Commands
       class ProjectNew < Command
         USAGE_LINE = "plastic project new SLUG --path PATH [--parent ID] [--json]"
 
+        SLUG = /\A[a-z0-9][a-z0-9-]*\z/
+        RESERVED = "global"
+
         def initialize(argv, runner: nil, **streams)
           super(argv, **streams)
           @runner = runner
@@ -24,9 +29,14 @@ module Plastic
         def call
           raise Usage, "SLUG is required" if slug.to_s.empty?
           raise Usage, "--path is required" if options[:path].to_s.empty?
+          unless slug.match?(SLUG) && slug != RESERVED
+            raise Usage, "SLUG must be lowercase letters, digits and hyphens, start with a letter or digit, and not be global"
+          end
           raise Failure, "#{options[:path]} does not exist" unless Dir.exist?(options[:path])
           raise Failure, "#{options[:path]} has no AGENTS.md; write one first" unless File.file?(File.join(options[:path], "AGENTS.md"))
           raise Failure, "#{slug} is already registered" if StoreProvisioning.registered?(slug, scope.plastic_home)
+          owner = slug_for_path
+          raise Failure, "#{options[:path]} is already registered as #{owner}" if owner
 
           register
           run("provision-project-store", slug, "--home", scope.plastic_home)
@@ -45,6 +55,19 @@ module Plastic
           parser.on("--parent ID") { |v| @options[:parent] = v }
         end
 
+        def slug_for_path
+          path = File.realpath(options[:path])
+          projects.find do |_slug, info|
+            registered = info.is_a?(Hash) && info["path"].is_a?(String) && info["path"]
+            registered && Dir.exist?(registered) && File.realpath(registered) == path
+          end&.first
+        end
+
+        def projects
+          data = File.exist?(projects_yml) ? YAML.safe_load_file(projects_yml) : nil
+          (data.is_a?(Hash) && data["projects"].is_a?(Hash)) ? data["projects"] : {}
+        end
+
         def projects_yml
           File.join(scope.plastic_home, "projects.yml")
         end

package/scripts/lib/cli/commands/render.rb

@@ -8,6 +8,8 @@ module Plastic
       class Render < Command
         USAGE_LINE = "plastic render FILE"
         STYLE = File.expand_path("../../../../templates/render.css", __dir__)
+        # A leading YAML block is metadata; RDoc would render it as body text.
+        FRONTMATTER = /\A---\r?\n.*?^---[ \t]*(\r?\n|\z)/m
 
         def call
           file = arguments.first or raise Usage, "FILE is the markdown file to render"
@@ -15,7 +17,7 @@ module Plastic
 
           require "rubygems"
           require "rdoc"
-          body = RDoc::Markdown.parse(File.read(file, encoding: "UTF-8")).accept(html_formatter)
+          body = RDoc::Markdown.parse(File.read(file, encoding: "UTF-8").sub(FRONTMATTER, "")).accept(html_formatter)
           @output.raw("<!doctype html>\n<meta charset=\"utf-8\">\n<title>#{File.basename(file)}</title>\n" \
             "<style>\n#{File.read(STYLE)}</style>\n#{body}")
         end

package/scripts/lib/cli/commands/roadmap_next.rb

@@ -15,6 +15,7 @@ module Plastic
         USAGE_LINE = "plastic roadmap next [--json]"
         AFTER = "plastic roadmap show SLUG"
         BECAUSE = "the winner it just named is the slug that command wants"
+        TIED = "the roadmaps tie; the first is shown, and any of them may be picked"
 
         def initialize(argv, runner: nil, **streams)
           super(argv, **streams)
@@ -24,7 +25,7 @@ module Plastic
         def call
           report = parse(*legacy.capture("roadmap-next", "--roadmaps-dir", scope.roadmaps_dir, "--which"))
           screen(report)
-          @output.next_step(after(report), because: BECAUSE)
+          @output.next_step(after(report), because: (report["state"] == "tie") ? TIED : BECAUSE)
         end
 
         private
@@ -38,10 +39,16 @@ module Plastic
         end
 
         def after(report)
-          slug = report["roadmap"].to_s
+          slug = (report["roadmap"] || tied(report).first).to_s
           slug.empty? ? AFTER : AFTER.sub("SLUG", slug)
         end
 
+        # roadmap-next --which reports a tie as state "tie" with "tie" false and
+        # each candidate as an object; older reports carried plain names.
+        def tied(report)
+          Array(report["tie_candidates"]).map { |candidate| candidate.is_a?(Hash) ? candidate["roadmap"] : candidate }
+        end
+
         def screen(report)
           @output.row("state", report["state"])
           @output.row("roadmap", report["roadmap"] || "none")
@@ -49,7 +56,7 @@ module Plastic
           @output.row("next", queue(report["dispatchable_queue"]))
           @output.row("delivering", entries(report["in_flight"]))
           @output.row("blocked", entries(report["blocked"]))
-          @output.row("tie", Array(report["tie_candidates"]).join(", ")) if report["tie"]
+          @output.row("tie", tied(report).join(", ")) if report["tie"] || report["state"] == "tie"
         end
 
         def queue(list)

package/scripts/lib/cli/commands/roadmap_show.rb

@@ -2,6 +2,7 @@
 
 require_relative "../command"
 require_relative "../legacy"
+require_relative "../../roadmap_graph"
 
 # `plastic roadmap show` - a roadmap's state screen (`report-screen roadmap
 # FILE state`, run through Legacy). SLUG is required: `plastic roadmap next`
@@ -23,11 +24,30 @@ module Plastic
           status = legacy.run("report-screen", "roadmap", path, "state")
           raise Failure, "report-screen exited #{status}" unless status.zero?
 
-          @output.next_step("plastic roadmap log #{slug} EVENT \"TEXT\"", because: "a savepoint is how this state screen keeps moving")
+          problems = graph_problems
+          problems.each { |problem| @output.row("warning", problem) }
+          if problems.empty?
+            @output.next_step("plastic roadmap log #{slug} EVENT \"TEXT\"", because: "a savepoint is how this state screen keeps moving")
+          else
+            @output.next_step("plastic roadmap check #{slug}", because: "the graph has problems the state screen cannot show")
+          end
         end
 
         private
 
+        # A cycle or a graph id no batch lists (acceptance N8). The state screen
+        # cannot show either, so they are named under it.
+        def graph_problems
+          return [] unless File.file?(path)
+
+          result = RoadmapGraph.analyze(path)
+          problems = []
+          problems << "cyclic graph: #{result[:cycle].join(" > ")}" if result[:cycle]
+          dangling = Array(result[:dangling])
+          problems << "graph names #{dangling.join(", ")}, no batch entry" unless dangling.empty?
+          problems
+        end
+
         def slug
           arguments.first
         end

package/scripts/lib/cli/commands/session_commit.rb

@@ -24,7 +24,7 @@ module Plastic
           status = legacy.run("session-commit", "--cwd", @directory, "--summary", summary)
           raise Failure, "session-commit exited #{status}" unless status.zero?
 
-          @output.next_step("plastic session handoff", because: "a handoff after a commit keeps the day ledger current")
+          @output.next_step("plastic session handoff", because: "the line above says whether a commit landed; a handoff keeps the day ledger current")
         end
 
         private

package/scripts/lib/cli/commands/sync.rb

@@ -10,9 +10,14 @@ module Plastic
       class Sync < Command
         USAGE_LINE = "plastic sync [--dry-run] [--json]"
 
+        # Rebuilt on every sync; a missing one is named in the plan, so the
+        # preview and the sync report the same work (acceptance N7).
+        DERIVED = [WorkGraph, ReferenceArchive].freeze
+
         def call
           home = scope.plastic_home
           plan = File.exist?(SearchIndex.path(home)) ? StoreSync.plan(home) : [["build", SearchIndex::NAME]]
+          plan += DERIVED.reject { |database| File.exist?(database.path(home)) }.map { |database| ["build", database::NAME] }
           refuse(home, plan.filter_map { |action, path| path if action == "conflict" })
           plan.group_by(&:first).each { |action, pairs| @output.row(action, pairs.map(&:last)) }
           @output.row("result", "nothing to do") if plan.empty?
@@ -36,7 +41,11 @@ module Plastic
         end
 
         def apply(home, plan)
-          (plan == [["build", SearchIndex::NAME]]) ? SearchIndex.build(home) : StoreSync.apply(home, plan)
+          if plan.include?(["build", SearchIndex::NAME])
+            SearchIndex.build(home)
+          else
+            StoreSync.apply(home, plan.reject { |step| step.first == "build" })
+          end
           WorkGraph.build(home)
           ReferenceArchive.build(home)
         end

package/scripts/lib/hook_replay.rb

@@ -3,7 +3,6 @@
 
 require "json"
 require "open3"
-require "timeout"
 
 # HookReplay (intent 331a, T1; promoted to a production lib in 331e) - streams
 # text through a MessageDisplay launcher the way Claude Code streams an
@@ -31,14 +30,9 @@ module HookReplay
   # environment. Default `{}` keeps every existing caller's behavior
   # unchanged: this is an extension, not a fork.
   #
-  # `timeout` (intent 331e): when given, bounds EACH chunk's spawn to that
-  # many seconds. A bare `Timeout.timeout` around `Open3.capture3` does not
-  # reliably bound a genuinely hanging child: capture3's own wait still
-  # blocks on Process.waitpid for the child regardless of the raised
-  # Timeout::Error (the same gotcha scripts/hook-record works around), so a
-  # timeout here spawns directly and kills the child on expiry instead.
-  # Default `nil` keeps every existing caller on the original unbounded
-  # Open3.capture3 path.
+  # `timeout` (intent 331e): when given, bounds each chunk's whole exchange to
+  # that many seconds (see run_bounded). Default `nil` keeps every existing
+  # caller on the original unbounded Open3.capture3 path.
   def replay(hook_path:, tmp_root:, text:, chunk: 40, session_id: "s-replay", message_id: "replay",
               env: {}, timeout: nil)
     chunks = text.scan(/.{1,#{chunk}}/m)
@@ -168,46 +162,58 @@ module HookReplay
     [out, err, status.exitstatus]
   end
 
-  # Spawn directly (never Open3.capture3) so a timeout can actually kill the
-  # child, with stdin/stdout/stderr routed through scratch files under the
-  # caller's own tmp_root, and never pipes, so a stalled or oversized write can
-  # never deadlock the read side, and never anywhere outside tmp_root, so a
-  # bounded replay carries the same "writes only under the injected tmp
-  # root" guarantee as the unbounded path.
-  def run_bounded(hook_path, payload, full_env, tmp_root, timeout)
-    token = "#{Process.pid}-#{(Time.now.to_f * 1_000_000).to_i}-#{rand(1_000_000)}"
-    in_path = File.join(tmp_root, ".hook-replay-in-#{token}")
-    out_path = File.join(tmp_root, ".hook-replay-out-#{token}")
-    err_path = File.join(tmp_root, ".hook-replay-err-#{token}")
-    File.write(in_path, JSON.generate(payload))
-
-    pid = Process.spawn(full_env, hook_path, in: in_path, out: out_path, err: err_path)
-    exitstatus =
-      begin
-        Timeout.timeout(timeout) { Process.wait(pid) }
-        $?.exitstatus
-      rescue Timeout::Error
-        kill_and_reap(pid)
-        nil # nil exitstatus is the caller's signal that this chunk timed out
-      end
-
-    out = File.exist?(out_path) ? File.read(out_path) : ""
-    err = File.exist?(err_path) ? File.read(err_path) : ""
-    [out, err, exitstatus]
+  # Bounded run over pipes (acceptance N9). Scratch files for the child's
+  # stdin and stdout broke on Snap Ruby: the launcher's `ruby` could neither
+  # read nor write them, so every chunk came back empty with exit 1. Pipes
+  # work there, as the unbounded path already shows.
+  #
+  # One deadline covers the whole exchange: the launcher's exit, feeding
+  # stdin, and draining stdout and stderr. A launcher can exit while a child
+  # it started keeps the pipes open, so waiting for the launcher alone is not
+  # enough. A writer thread feeds stdin and reader threads drain both outputs
+  # at the same time, so large input or output cannot block.
+  #
+  # The launcher leads its own process group. When the deadline passes, the
+  # whole group is killed, the pipes are closed, and the result carries the
+  # output read so far with a nil exitstatus: the caller's signal that this
+  # chunk timed out. Nothing is written under tmp_root.
+  def run_bounded(hook_path, payload, full_env, _tmp_root, timeout)
+    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+    stdin, stdout, stderr, wait = Open3.popen3(full_env, hook_path, pgroup: true)
+    buffers = [String.new, String.new]
+    threads = [Thread.new { feed(stdin, JSON.generate(payload)) }] +
+      [stdout, stderr].zip(buffers).map { |io, buffer| Thread.new { drain(io, buffer) } }
+    finished = [wait, *threads].all? { |thread| thread.join(remaining(deadline)) }
+    kill_group(wait.pid) unless finished
+    buffers.map { |buffer| buffer.force_encoding(Encoding.default_external) } +
+      [finished ? wait.value.exitstatus : nil]
   ensure
-    [in_path, out_path, err_path].each { |p| File.delete(p) if p && File.exist?(p) }
+    [stdin, stdout, stderr].compact.each { |io| io.close unless io.closed? }
+    threads&.each { |thread| thread.join(1) }
   end
 
-  def kill_and_reap(pid)
-    Process.kill("KILL", pid)
-  rescue StandardError
-    nil
+  def remaining(deadline)
+    [deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max
+  end
+
+  def feed(io, data)
+    io.write(data)
+  rescue IOError, SystemCallError
+    # the hook exited without reading its input, or the deadline closed the pipe
   ensure
-    begin
-      Process.wait(pid)
-    rescue StandardError
-      nil
-    end
+    io.close unless io.closed?
+  end
+
+  def drain(io, buffer)
+    loop { buffer << io.readpartial(65_536) }
+  rescue IOError, SystemCallError
+    # end of output, or the deadline closed the pipe
+  end
+
+  def kill_group(pid)
+    Process.kill("KILL", -pid)
+  rescue SystemCallError
+    nil # the whole group has already exited
   end
 
   # The final chunk's parsed displayContent, or nil when it emitted nothing

package/scripts/lib/installer_core.rb

@@ -71,6 +71,17 @@ class InstallerCore
 
   attr_reader :package_root, :plastic_home, :version, :agents
 
+  def store_layout_compatible?(target)
+    !Plastic::StoreLayout.moved?(plastic_home) || semver_compare(target, "2.0.0-alpha.28") >= 0
+  end
+
+  def refuse_incompatible_store_layout(target)
+    return if store_layout_compatible?(target)
+
+    warn "Plastic #{target} cannot read stores/ in #{plastic_home}. Keep a version that supports this layout."
+    true
+  end
+
   def initialize(package_root:, plastic_home: DEFAULT_PLASTIC_HOME, version: nil, agents: DEFAULT_AGENTS)
     @package_root = package_root
     @plastic_home = plastic_home
@@ -405,6 +416,7 @@ class InstallerCore
       "scripts/lib/index_entry.rb" => "scripts/lib/index_entry.rb",
       "scripts/lib/project_config.rb" => "scripts/lib/project_config.rb",
       "scripts/lib/savepoint.rb" => "scripts/lib/savepoint.rb",
+      "scripts/lib/untouched_scaffold.rb" => "scripts/lib/untouched_scaffold.rb",
       "scripts/lib/guarded_append.rb" => "scripts/lib/guarded_append.rb",
       "scripts/lib/node_ledger.rb" => "scripts/lib/node_ledger.rb",
       "scripts/lib/node_input_compatibility.rb" => "scripts/lib/node_input_compatibility.rb",

package/scripts/lib/node_input.rb

@@ -36,6 +36,10 @@ module NodeInput
   # reports is not provisioned.
   STOP_DIRECTIVE = "STOP: no lease is recorded for this node. Do not edit files or run any command until a runner dispatches this node with a holder, an expiry and a model."
 
+  # A work node whose worktree is missing gets its own reason (acceptance
+  # N12): the lease may be fine, and saying it is missing contradicts it.
+  WORKTREE_STOP_DIRECTIVE = "STOP: no worktree is provisioned for this node. Do not edit files until a runner dispatches it into one."
+
   # Pinned so `input=<sha>` is a function of the repo's history alone
   # (post-execution review finding B4): unpinned, `git log --stat` varies
   # with the terminal's COLUMNS (abbreviates paths, narrows the graph
@@ -386,12 +390,17 @@ module NodeInput
 
   # --- block 5: where to work (instruction) ---------------------------------
 
+  # A node kind that needs no worktree (research, verify) is marked
+  # `read_only` by the runner: it reads the repository and edits nothing, so
+  # the absent worktree is expected and carries no stop directive.
   def worktree_block(intent_dir:, worktree_reader: Arm.method(:worktree_block))
     info = worktree_reader.call(intent_dir: intent_dir)
     if info && info["provisioned"]
       "worktree: #{info['code']} (branch #{info['code_branch']})"
+    elsif info && info["read_only"]
+      "worktree: none; this node reads the repository and edits nothing"
     else
-      "worktree: none provisioned\n#{STOP_DIRECTIVE}"
+      "worktree: none provisioned\n#{WORKTREE_STOP_DIRECTIVE}"
     end
   end
 
@@ -445,9 +454,8 @@ module NodeInput
 
   # `lease_missing` (post-execution review finding A1) hoists C7's stop
   # directive here, block 5 (instruction, spec D3), whenever the node input
-  # carries no lease. `worktree_block` already renders its own copy when the
-  # worktree is unprovisioned; the two conditions often fire together, so a
-  # directive already present is never repeated.
+  # carries no lease. A missing worktree has its own directive, so each stop
+  # line names its own reason.
   #
   # `call_cap` (intent 355, n2, D2): one sentence naming this attempt's tool
   # call cap and the return it hits at, so the executor learns the number
@@ -458,7 +466,7 @@ module NodeInput
                            files: [])
     wt = worktree_block(intent_dir: intent_dir, worktree_reader: worktree_reader)
     parts = [wt, test_command_block(intent_dir: intent_dir, files: files, project_reader: project_reader)]
-    parts << STOP_DIRECTIVE if lease_missing && !wt.include?(STOP_DIRECTIVE)
+    parts << STOP_DIRECTIVE if lease_missing
     parts << call_cap_sentence(call_cap) if call_cap
     parts.join("\n")
   end

package/scripts/lib/revisions_writer.rb

@@ -3,8 +3,7 @@
 
 # RevisionsWriter - the shared append-only revisions.md writer (intent 107's convention,
 # generalized from restore_intent_v1.rb's proven pattern, intent 197). Every tool that
-# performs structural maintenance on an intent (project-links, rebuild-graph,
-# restore-intent-v1) must record it here: PLASTIC.md's `revisions.md` contract is that a
+# uses this writer (project-links, rebuild-graph, or rebuild-savepoint) records changes here: PLASTIC.md's `revisions.md` contract is that a
 # structural change and its receipt are never separated. This module owns rendering ONE
 # entry's text and appending it correctly; it does no git operations (that is
 # lib/maintenance_git.rb's job) and never overwrites a prior entry.

package/scripts/lib/roadmap_queue.rb

@@ -224,18 +224,26 @@ class RoadmapQueue
 
   # --- liveness ranking (ports plastic-intent-continuing's read-time algorithm) -
 
+  # A roadmap whose graph has a cycle cannot compute a frontier, so it ranks
+  # after every healthy one (acceptance N8). It still wins when nothing else
+  # is left, and the payload then reports the cycle as an error.
   def rank_candidates(parsed_list)
     parsed_list.map do |c|
       entries = c[:waves].flat_map { |w| w[:entries] }
       live = entries.any? { |e| %w[delivering blocked].include?(e[:status]) }
-      c.merge(live: live, last_event: last_event_time(c[:path]))
-    end.sort_by { |c| [c[:live] ? 0 : 1, -c[:last_event].to_i, c[:slug]] }
+      cyclic = !!(c[:graph_edges] && GraphEdges.cycle(c[:graph_edges][:edges]))
+      c.merge(live: live, cyclic: cyclic, last_event: last_event_time(c[:path]))
+    end.sort_by { |c| rank_key(c) + [c[:slug]] }
+  end
+
+  def rank_key(candidate)
+    [candidate[:cyclic] ? 1 : 0, candidate[:live] ? 0 : 1, -candidate[:last_event].to_i]
   end
 
   def tied_group(ranked)
     return [] if ranked.empty?
-    top_key = [ranked.first[:live], ranked.first[:last_event].to_i]
-    ranked.select { |c| [c[:live], c[:last_event].to_i] == top_key }
+    top_key = rank_key(ranked.first)
+    ranked.select { |c| rank_key(c) == top_key }
   end
 
   def last_event_time(path)