@zalom/plastic 2.0.0-alpha.21 → 2.0.0-alpha.23

package/scripts/runner

@@ -2,24 +2,28 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require "yaml"
+require "stringio"
 require_relative "lib/savepoint"
 require_relative "lib/ready_set"
 require_relative "lib/runner_core"
+require_relative "lib/harness_adapter"
 require_relative "lib/runner_proposals"
 
 # runner - the one executable over the graph-ready loop's declared node graph
 # (intent 340, G7, n1). A subcommand table: the public verbs (step, status,
 # answer) are the only ones the skill body ever names; the internal verbs
-# (ready, sweep, rewind) route and work so `step` can compose them and so
-# each can be tested alone, but stay out of the usage text (327 spec).
+# (ready, sweep, rewind, until-empty) route and work so `step` can compose
+# them and so each can be tested alone, but stay out of the usage text (327
+# spec, 340b n7).
 #
-# `step`, `sweep`, `answer` and `rewind` route to modules later nodes
-# deliver (RunnerDispatch and RunnerAbsorb for `step`; RunnerSweep,
-# RunnerAnswer, RunnerRewind for the rest). Each is required LAZILY, inside
-# its own verb branch: a verb whose module has not landed yet reports
-# plainly and exits nonzero, and every other verb - most importantly
-# `status`, which an operator polls constantly across all five of this
-# intent's dispatches - keeps working.
+# `step`, `sweep`, `answer`, `rewind` and `until-empty` route to modules
+# later nodes deliver (RunnerDispatch and RunnerAbsorb for `step`;
+# RunnerSweep, RunnerAnswer, RunnerRewind, RunnerUntilEmpty for the rest).
+# Each is required LAZILY, inside its own verb branch: a verb whose module
+# has not landed yet reports plainly and exits nonzero, and every other verb
+# - most importantly `status`, which an operator polls constantly across all
+# five of this intent's dispatches - keeps working.
 #
 # Usage:
 #   runner <step|status|answer> <intent_dir> [--node ID] [--answer TEXT]
@@ -34,7 +38,7 @@ module Runner
   module_function
 
   PUBLIC_VERBS = %w[step status answer].freeze
-  INTERNAL_VERBS = %w[ready sweep rewind].freeze
+  INTERNAL_VERBS = %w[ready sweep rewind until-empty watch].freeze
   VERBS = (PUBLIC_VERBS + INTERNAL_VERBS).freeze
 
   # verb -> [[ModuleName, lib_file], ...], required lazily inside the verb's
@@ -47,6 +51,8 @@ module Runner
     "sweep" => [["RunnerSweep", "runner_sweep"]],
     "answer" => [["RunnerAnswer", "runner_answer"]],
     "rewind" => [["RunnerRewind", "runner_rewind"]],
+    "until-empty" => [["RunnerUntilEmpty", "runner_until_empty"]],
+    "watch" => [["RunnerWatch", "runner_watch"]],
   }.freeze
 
   def usage
@@ -77,11 +83,21 @@ module Runner
   # a mistyped `--session` used to vanish with no effect and the runner
   # simply acted as whichever session `CLAUDE_CODE_SESSION_ID` names.
   KNOWN_FLAGS = {
-    "step" => %w[--return --allow-core-drift],
+    "step" => %w[--return --allow-core-drift --harness],
     "answer" => %w[--node --answer],
     "rewind" => %w[--node --confirm],
+    "until-empty" => %w[--harness],
+    "watch" => %w[--dispatch --harness --install-timer --home],
   }.freeze
 
+  # The explicit YAML document-end marker (intent 340b, G7c, n1, row 1.28)
+  # separating the dispatch plan `step` has always printed from the
+  # harness-rendered block underneath it: stdout has never been one YAML
+  # document (absorb/reclaim/extend/reap lines print before the plan,
+  # decision/park lines after it), so a reader splits on this marker rather
+  # than guessing where the plan ends.
+  DOCUMENT_BOUNDARY = "...".freeze
+
   # unrecognized_flag(verb, args) -> the first token in `args` that looks
   # like a flag (`--...`) and is not in `verb`'s own KNOWN_FLAGS, or nil. A
   # verb absent from KNOWN_FLAGS (status, ready, sweep) accepts none.
@@ -203,6 +219,10 @@ module Runner
       run_answer(intent_dir, args)
     when "rewind"
       run_rewind(intent_dir, args)
+    when "until-empty"
+      run_until_empty(intent_dir, args)
+    when "watch"
+      run_watch(intent_dir, args)
     else
       warn "runner: #{verb}'s module loaded but no dispatcher is wired up yet"
       exit 3
@@ -284,14 +304,156 @@ module Runner
     exit 0
   end
 
-  # run_step (intent 340, G7, n5): one turn of the loop, in the fixed order
-  # 327 D14 and RunnerSweep's own docstring name - abort on a stuck merge,
-  # the delivery-lease heartbeat, absorb every `--return NODE=PATH` this call
-  # carries, THEN reclaim (so a node this very call just absorbed is never
-  # reclaimed out from under its own return, matrix row 2.19/2.20) - and only
-  # then dispatch whatever is left ready. Never spawns an agent (327 D42):
-  # the session makes every subagent call from the plan this prints.
+  # run_until_empty (intent 340b, G7c, n7): the Codex loop. Internal, like
+  # `rewind` (row 7.13) - `RunnerUntilEmpty.run` composes `step` and
+  # `node-run` itself, since Codex has no session on the other end to make
+  # the subagent calls `step` only ever prints a plan for. `--harness`
+  # threads into every turn the loop runs (row 7.5), never re-resolved per
+  # iteration from a literal. The lock check here is the same defence in
+  # depth `run_step_body` carries (B4): `RunnerUntilEmpty.step_once` refuses
+  # `lock_not_held` on its own first call regardless, so this exits before
+  # even constructing the loop's own state.
+  def run_until_empty(intent_dir, args)
+    harness_override = opt(args, "--harness")
+    context = RunnerCore.context(intent_dir: intent_dir, env: ENV["CLAUDE_CODE_SESSION_ID"])
+
+    unless context.session
+      warn "runner: until-empty refused (lock_not_held)"
+      exit 1
+    end
+
+    result = RunnerUntilEmpty.run(context, harness: harness_override)
+
+    case result[:status]
+    when "complete", "stalled", "needs_decision", "iteration_cap"
+      exit 0
+    else
+      exit 1
+    end
+  end
+
+  # run_watch (intent 340a, G7b, n2): one tick over disk truth. Internal,
+  # like until-empty and rewind - the timer that carries it lives outside
+  # this process (a local `/loop` on Claude Code, a launchd job on Codex,
+  # n3/n4). `--dispatch` is unattended start (graph.md D7): refused here,
+  # before RunnerWatch.tick ever takes the tick lock or writes anything,
+  # when the resolved harness's `HarnessAdapter.unattended_start?` is
+  # false, so a refusal never leaves a `watch.record` line behind that
+  # looks like a completed tick.
+  # --install-timer (intent 340a, G7b, n3, graph.md D9): the Codex carrier.
+  # Writes the plist and prints the path plus the `launchctl load` command;
+  # never runs `launchctl` itself, so the owner stays in control of when the
+  # job actually loads. `--home` defaults to the OS home, as
+  # `scripts/meter-watch --install-timer` already does.
+  def run_watch(intent_dir, args)
+    dispatch = args.include?("--dispatch")
+    harness_override = opt(args, "--harness")
+    context = RunnerCore.context(intent_dir: intent_dir, env: ENV["CLAUDE_CODE_SESSION_ID"])
+    agent_config = load_agent_config(context.plastic_home)
+    harness = HarnessAdapter.resolve_key(config: agent_config, override: harness_override)
+
+    if args.include?("--install-timer")
+      home = opt(args, "--home") || Dir.home
+      plist_path = RunnerWatch.install_timer(context, home: home, harness_key: harness)
+      puts "plist: #{plist_path}"
+      puts "launchctl load #{plist_path}"
+      exit 0
+    end
+
+    if dispatch && !HarnessAdapter.unattended_start?(harness)
+      warn HarnessAdapter::UNATTENDED_START_SENTENCE
+      exit 1
+    end
+
+    result = RunnerWatch.tick(context, dispatch: dispatch, harness: harness)
+
+    puts "class: #{result[:class]}"
+    result[:blockers].each { |b| puts "blocked: #{b}" }
+    puts "ready: #{result[:ready].empty? ? '(none)' : result[:ready].join(', ')}"
+    puts "dispatched: #{result[:dispatched].empty? ? '(none)' : result[:dispatched].join(', ')}"
+    exit 0
+  end
+
+  # run_step (intent 340, G7, n5): one turn of the loop. The real work lives
+  # in #run_step_body below; this wrapper (intent 340b, G7c, n1, rows
+  # 1.21-1.25 and 1.29-1.31) exists ONLY to capture every byte `step` prints
+  # - stdout and stderr both, refusals included - and persist it to
+  # `<intent_dir>/runner-step.last` before the process actually exits, so a
+  # PreCompact hand-off (n3) always has something to render, even after one
+  # of the three pre-plan refusals that used to warn to stderr alone.
+  #
+  # `run_step_body` still calls Kernel#exit(N) at every one of its own exit
+  # points, exactly as before this node; wrapping it in a rescue for
+  # SystemExit lets this method capture the intended status, persist the
+  # file, replay the captured output onto the REAL stdout/stderr (so a
+  # subprocess caller like Open3.capture3 sees byte-identical output to
+  # before this node), and only then perform the one real process exit.
   def run_step(intent_dir, args)
+    out_buf = StringIO.new
+    err_buf = StringIO.new
+    real_stdout = $stdout
+    real_stderr = $stderr
+    exit_code = 0
+    begin
+      $stdout = out_buf
+      $stderr = err_buf
+      run_step_body(intent_dir, args)
+    rescue SystemExit => e
+      exit_code = e.status || 1
+    ensure
+      $stdout = real_stdout
+      $stderr = real_stderr
+    end
+
+    real_stdout.print(out_buf.string)
+    real_stderr.print(err_buf.string)
+    persist_runner_step_last(intent_dir, out_buf.string, err_buf.string)
+
+    exit(exit_code)
+  end
+
+  # Row 1.24: lives beside savepoint.md, never inside packets/ (which the
+  # reaper treats as attempt evidence). Row 1.32: registers itself in the
+  # store's own top-level `.gitignore` (Worktree.ensure_gitignored's own
+  # idempotent, non-raising append) the same way `*.lock` already is, so a
+  # file rewritten on every step never dirties the store tree. Row 1.25:
+  # wrapped in its own rescue - an unwritable intent directory must never
+  # crash a step that has already written its transitions.
+  def persist_runner_step_last(intent_dir, stdout_text, stderr_text)
+    home_root = Arm.home_for(intent_dir)
+    Worktree.ensure_gitignored(File.join(home_root, ".plastic"), "runner-step.last")
+
+    path = File.join(intent_dir, "runner-step.last")
+    File.write(path, "#{stdout_text}#{stderr_text}")
+  rescue StandardError => e
+    warn "runner: could not persist runner-step.last: #{e.message}"
+  end
+
+  # Intent 340b, G7c, n1, row 1.1: the config `HarnessAdapter.resolve_key`
+  # reads `agent.type` from. `context.plastic_home` is derived from the
+  # intent_dir's OWN ancestry (Arm.home_for -> Worktree.home_from_store), so
+  # a sandboxed test fixture never reaches the real ~/.plastic/config.yml
+  # (Arm.home_for's own docstring: "a sandboxed store never resolves to the
+  # real Dir.home") - this stays hermetic for free, the same way every other
+  # `context.plastic_home` read in this file already does. A missing or
+  # unparseable config.yml reads as {}, never raises.
+  def load_agent_config(plastic_home)
+    path = File.join(plastic_home.to_s, "config.yml")
+    return {} unless File.exist?(path)
+
+    YAML.safe_load(File.read(path)) || {}
+  rescue StandardError
+    {}
+  end
+
+  # run_step_body (intent 340, G7, n5): one turn of the loop, in the fixed
+  # order 327 D14 and RunnerSweep's own docstring name - abort on a stuck
+  # merge, the delivery-lease heartbeat, absorb every `--return NODE=PATH`
+  # this call carries, THEN reclaim (so a node this very call just absorbed
+  # is never reclaimed out from under its own return, matrix row 2.19/2.20) -
+  # and only then dispatch whatever is left ready. Never spawns an agent (327
+  # D42): the session makes every subagent call from the plan this prints.
+  def run_step_body(intent_dir, args)
     context = RunnerCore.context(intent_dir: intent_dir, env: ENV["CLAUDE_CODE_SESSION_ID"])
 
     # v1 minor 3/row 11.18: RunnerSweep.abort_if_merging already prints the
@@ -322,6 +484,12 @@ module Runner
     # never defaulted true.
     allow_core_drift = args.include?("--allow-core-drift")
 
+    # Intent 340b, G7c, n1, row 1.2/1.4: `--harness KEY` overrides config
+    # `agent.type` for this one call - how one machine drives both adapters
+    # without editing config. `nil` when absent, so HarnessAdapter falls
+    # through to config's own value untouched.
+    harness_override = opt(args, "--harness")
+
     returns = {}
     opt_all(args, "--return").each do |pair|
       node, path = pair.to_s.split("=", 2)
@@ -351,7 +519,8 @@ module Runner
     reaped = NodeWorktree.reap(context)
     reaped[:removed].each { |r| puts "reaped #{r[:node]} worktree" }
 
-    result = RunnerDispatch.dispatch(context)
+    agent_config = load_agent_config(context.plastic_home)
+    result = RunnerDispatch.dispatch(context, config: agent_config, harness: harness_override)
     unless result[:ok]
       warn "runner: step refused (#{result[:reason]}): #{Array(result[:errors]).join('; ')}"
       warn result[:rearm_command] if result[:rearm_command]
@@ -374,6 +543,21 @@ module Runner
       result[:blockers].each { |b| puts "blocked: #{b}" }
     end
 
+    # Intent 340b, G7c, n1, rows 1.6/1.13/1.14/1.27/1.28: the YAML plan keeps
+    # printing exactly as it did before this node (327's contract) - this is
+    # the rendered block UNDERNEATH it, for the harness `result[:harness]`
+    # resolved (config's `agent.type`, or this call's own `--harness`
+    # override), separated by an explicit YAML document-end marker so a
+    # reader splits on that marker rather than a heuristic. `render` returns
+    # nil for an empty dispatch list (row 1.14), so nothing extra ever
+    # prints when this step dispatched nothing.
+    block = HarnessAdapter.render(result[:dispatched], harness: result[:harness],
+                                   return_contract: RunnerDispatch::RETURN_CONTRACT)
+    if block
+      puts DOCUMENT_BOUNDARY
+      puts block
+    end
+
     # M11/row 10.14: a `needs_decision` stop must print even when THIS SAME
     # step also dispatched other nodes ahead of the decision node in ranked
     # order - `result[:status]` reads "dispatched" in that case (dispatched

package/scripts/skill-lint

@@ -2,11 +2,13 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-# skill-lint: deterministic CLI over SkillLint (intent 85b).
+# skill-lint: deterministic CLI over SkillLint (intent 85b), plus one CLI-local
+# check (intent 341, G8, n1, C35).
 #
-# Runs the five structural skill checks (body-budget, frontmatter-validity,
-# bare-pointer, orphan-files, references-depth) over a directory of Agent
-# Skills and reports every violation. Mirrors `scripts/validate-intent`'s
+# Runs the five structural checks (body-budget, frontmatter-validity,
+# bare-pointer, orphan-files, references-depth) via SkillLint, then this
+# script's own refusal-restatement check, over a directory of Agent Skills,
+# and reports every violation. Mirrors `scripts/validate-intent`'s
 # CLI-over-lib shape and exit-code contract.
 #
 # Usage:
@@ -17,6 +19,112 @@
 
 require_relative "lib/skill_lint"
 
+# RefusalRestatementCheck (C35): a skill body must not restate, past a short
+# run of words, a refusal rule the conventions chapter already carries; it
+# must link that chapter instead. No-op when <skills_dir>/conventions/references
+# does not exist, so an older tree or a fixture dir with no conventions chapter
+# is unaffected.
+#
+# Deliberately lives in this CLI, not in scripts/lib/skill_lint.rb: C35 is a
+# doctrine-duplication check, one level removed from SkillLint's five
+# structural checks, and keeping it here means adding it touches only the
+# files this change is scoped to.
+class RefusalRestatementCheck
+  REFUSAL_KEYWORD_RE = /\brefus(e|es|ed|ing|al)\b/i
+  CONVENTIONS_LINK_RE = %r{conventions/references/|plastic-conventions}i
+
+  # How many consecutive normalized words must match, verbatim, between a
+  # skill's refusal paragraph and the doctrine text before it counts as a
+  # restatement rather than a coincidental shared phrase.
+  NGRAM = 6
+
+  def initialize(skills_dir)
+    @skills_dir = skills_dir
+  end
+
+  def run
+    doctrine = doctrine_blob
+    return [] unless doctrine
+
+    skill_md_paths.flat_map do |skill_md|
+      skill_dir = File.dirname(skill_md)
+      next [] if File.basename(skill_dir) == "conventions" # the source never restates itself
+
+      check_skill(skill_dir, skill_md, File.read(skill_md), doctrine)
+    end
+  end
+
+  private
+
+  def skill_md_paths
+    Dir.glob(File.join(@skills_dir, "*", "SKILL.md")).sort
+  end
+
+  def doctrine_blob
+    chapters = Dir.glob(File.join(@skills_dir, "conventions", "references", "*.md")).sort
+    return nil if chapters.empty?
+
+    text = chapters.map { |f| File.read(f) }.join(" ")
+    " #{normalize_words(text).join(" ")} "
+  end
+
+  def normalize_words(text)
+    text.downcase.gsub("`", "").gsub(/[^a-z0-9\s-]/, " ").split(/\s+/).reject(&:empty?)
+  end
+
+  # Same split as SkillLint's own frontmatter/body divide: `content.split("---", 3)`.
+  def body_and_offset(content)
+    parts = content.split("---", 3)
+    return [content, 0] if parts.length < 3
+
+    prefix_len = parts[0].length + 3 + parts[1].length + 3
+    [parts[2], content[0...prefix_len].count("\n")]
+  end
+
+  # Blank-line-delimited paragraph blocks, so a refusal keyword and its
+  # doctrine echo are compared across the whole paragraph, not one line.
+  def paragraph_blocks(lines)
+    blocks = []
+    start = nil
+    lines.each_with_index do |line, i|
+      if line.strip.empty?
+        blocks << { start: start, text: lines[start..(i - 1)].join } if start
+        start = nil
+      else
+        start ||= i
+      end
+    end
+    blocks << { start: start, text: lines[start..].join } if start
+    blocks
+  end
+
+  def restated?(block_text, doctrine)
+    words = normalize_words(block_text)
+    return false if words.length < NGRAM
+
+    (0..(words.length - NGRAM)).any? do |i|
+      doctrine.include?(" #{words[i, NGRAM].join(" ")} ")
+    end
+  end
+
+  def check_skill(skill_dir, skill_md, content, doctrine)
+    name = File.basename(skill_dir)
+    body, offset = body_and_offset(content)
+
+    paragraph_blocks(body.lines).filter_map do |block|
+      next unless block[:text].match?(REFUSAL_KEYWORD_RE)
+      next if block[:text].match?(CONVENTIONS_LINK_RE) # links the chapter instead of restating
+      next unless restated?(block[:text], doctrine)
+
+      {
+        check: "refusal-restatement", skill: name, file: skill_md, line: offset + block[:start] + 1,
+        message: "this paragraph restates a refusal rule word-for-word from " \
+                  "skills/conventions/references/; link the chapter instead of repeating its text",
+      }
+    end
+  end
+end
+
 def resolve_skills_dir(args)
   if (i = args.index("--skills-dir"))
     args[i + 1]
@@ -37,14 +145,15 @@ end
 
 dir = File.expand_path(resolve_skills_dir(ARGV))
 result = SkillLint.new(skills_dir: dir).run
+violations = result.violations + RefusalRestatementCheck.new(dir).run
 
-if result.ok?
+if violations.empty?
   puts "OK: #{dir}"
   exit 0
 end
 
 warn "VIOLATIONS: #{dir}"
-result.violations.each do |v|
+violations.each do |v|
   warn "#{v[:check]} #{v[:skill]} #{v[:file]}:#{v[:line].nil? ? "-" : v[:line]} #{v[:message]}"
 end
 exit 1

package/scripts/verify-intent

@@ -11,7 +11,7 @@
 #
 # --base overrides the auto-detected diff base (default: the merge base with the repo's
 # detected default branch) for repos where detection is ambiguous. --suite is an optional
-# caller-supplied command to run (in the repo directory) and fold into the verdict. No
+# caller-supplied command to run (in the repo directory) and merge into the verdict. No
 # other flags exist.
 #
 # Checks, all run every invocation (the fourth only when --suite is given):

package/skills/auto/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: plastic-auto
 description: >-
-  Autonomous intent delivery - a background team takes a registered intent from How to Done.
+  Autonomous intent delivery - a background team takes a registered intent from How to End.
   Use when user says "auto", "take it from here", "deliver this", or when a thinking
   conversation concludes and the user confirms autonomous execution. Requires an active intent
   in INDEX.md.
@@ -71,35 +71,29 @@ owner override. Do not proceed as the owner after an exit 1.
 Read `../plastic-conventions/references/locks-and-worktrees.md` for what the lock and the
 worktree mean and the station table behind them. Code edits happen only inside the worktree.
 
-## The shape (five steps, two agent boots)
+## The shape
 
-Every auto delivery runs the same shape, ruled by the owner on 2026-08-29. There is no intent
-tier and no stage agent; depth follows the work.
+Work is a graph (`graph.md`: Goal, Decisions, Graph, Status; one `nodes/*.md` per node) or,
+for work small enough to skip speccing, delivered inline with no separate plan review. There
+is no intent tier and no stage agent; depth follows the work.
 
-| Step | Who | What lands |
-|---|---|---|
-| 1. The lead writes How | this session | `plan.md`, at least one `actions/ACTION_N.md` carrying a failure-mode matrix (one row per operation: the failure and the test that catches it), `checklist.md` |
-| 2. Adversarial plan review | boot 1, a fresh agent on `plan-reviewer-prompt.md` | a review file; the lead folds every finding into the spec, the matrix, and the tests |
-| 3. Execute, tests first | boot 2, `plastic-executor` | the red commit (the matrix's tests, failing), then the code, then a green suite |
-| 4. Review by risk | boot 3 only when risk calls for it (below) | a pass or a list of fixes the executor applies |
-| 5. One suite run, then close | this session | `outcome.md`, `end-intent`, the roadmap ledger |
+`runner step` computes readiness and prints a spawn block per dispatched node - agent, model,
+packet path, the test command, the call cap - fenced for a session to paste into the Agent
+tool; the runner never spawns (327 D42). `runner status` renders the ledger; `runner answer`
+closes a `needs_decision` node.
 
-Two boots is the normal delivery; the third is the exception the risk rule names. The lead is
-this session (the `plastic-enforcer` role), never a dispatched agent.
-
-A lead is a choice, not a requirement (D8, 355). `runner step` computes the plan and prints a
-spawn block per node - agent, model, packet path, the test command, the call cap - fenced for a
-session to paste into the Agent tool; the runner never spawns (327 D42). A lead earns its keep
-on a graph carrying a decision node, weighing its `needs_decision` stop; a graph with none runs
-end to end from `runner step` alone.
+A lead is a choice, not a requirement (D8, 355). A lead earns its keep on a graph carrying a
+decision node, weighing its `needs_decision` stop; a graph with none runs end to end from
+`runner step` alone. When this session leads, it is the `plastic-enforcer` role, never a
+dispatched agent.
 
 ## Team
 
-- **plastic-enforcer**: this session. Writes the Why and How record, dispatches, folds reviews,
-  verifies, closes.
+- **plastic-enforcer**: this session. Writes the Why and How record, dispatches, applies
+  review findings, verifies, closes.
 - **plastic-executor**: one dispatch per intent, implements the consolidated action tests first,
   ticks the checklist, appends `## Insights`, drives the suite green.
-- **the plan reviewer**: one dispatch before code, from `plastic-intent-executing`'s
+- **the plan reviewer**: an optional dispatch before code, from `plastic-intent-executing`'s
   `plan-reviewer-prompt.md`; a fresh agent, never the lead.
 - **the post-execution reviewer**: dispatched only by the risk rule, from
   `code-quality-reviewer-prompt.md`; a fresh agent, never the maker.
@@ -154,7 +148,9 @@ Only the owner can delegate. Delegates cannot re-delegate or release.
 Headless note: in a headless or background run the session id may be unset; the arm verb then keys the lock by a derived key and the record hook still writes the ledger.
 Verify with `plastic-lock status` rather than assuming.
 
-Solo fallback: on a harness with no agent dispatch (Codex CLI today), this session walks the five steps itself, still writing the matrix and the tests first and reviewing its own plan against the matrix before code, saying so in `## Insights`.
+Solo fallback: on a harness with no agent dispatch (Codex CLI today), this session walks the
+graph (or the plan) itself, still writing the matrix and the tests first and reviewing its own
+plan against the matrix before code, saying so in `## Insights`.
 
 ## Stage-Aware Entry
 
@@ -168,8 +164,8 @@ ledger is missing (then rebuild it with `Savepoint.rebuild_savepoint`).
 | `Why  spec.md created` | How |
 | `How  plan.md created` / `How  checklist.md created` / `Exec  started` | Exec (verify plan, matrix, checklist) |
 | `Exec  outcome.md created` | Exec done; complete the intent |
-| `Done  delivered|abandoned` | Terminal; do not resume |
-| A node or `Intent` transition line (`n1  running ...`, `Intent  needs_decision ...`) | Exec; a graph delivery is in progress - drive it through `scripts/runner`'s three public verbs, `step` (one turn of the dispatch loop), `status` (renders ledger state, safe to poll constantly), and `answer` (closes a `needs_decision` node) - read node status through `NodeLedger.status` before dispatching anything, never re-derive it by eye |
+| A terminal savepoint line (`delivered` or `abandoned`) | Terminal; do not resume |
+| A node or `Intent` transition line (`n1  running ...`, `Intent  needs_decision ...`) | Exec; a graph delivery is in progress - drive it through `scripts/runner`'s three public verbs, `step` (one turn of the dispatch loop), `status` (renders ledger state, safe to poll constantly), and `answer` (closes a `needs_decision` node) - read node status through `NodeLedger.status` before dispatching anything, never re-derive it by eye. `scripts/graph-measure` is the read-only sibling over that same ledger, with its own three public verbs `intent`, `budget`, and `cohorts` - it never dispatches and never writes |
 
 Filesystem fallback, in order: `checklist.md` with items checked means resume Exec from the
 first unchecked item; `plan.md` plus `checklist.md` means enter Exec; `spec.md` alone means
@@ -179,42 +175,43 @@ Announce which stage you are entering and why.
 
 ## Why (the lead)
 
-1. Read `## Context` and `### Decisions`; assess the gaps.
-2. Research yourself: code, docs, related intents through `## Links`, the web if needed. No
-   questions to the human.
-3. Decide: pick the best option per gap, record it in `## Context > ### Decisions` with the
-   rationale, and log it in `## Insights` with the `(autonomous)` marker through
-   `scripts/insight-append`.
-4. Write `spec.md`. Then How.
+For a graph delivery, Why is already written into `graph.md`'s Goal and Decisions; nothing
+else to do here. For work with no graph: read `## Context` and `### Decisions`, assess the
+gaps, research them yourself (code, docs, related intents through `## Links`, the web if
+needed; no questions to the human), record each decision in `## Context > ### Decisions` with
+its rationale, log it in `## Insights` with the `(autonomous)` marker through
+`scripts/insight-append`, and write `spec.md` only when the intent needs one (speccing is
+optional). Then How.
 
 ## How (the lead), then the plan review
 
-1. Write `plan.md`: numbered steps.
-2. Write at least one real `actions/ACTION_N.md` (one consolidated `ACTION_1.md` by default;
-   several only when the work splits into independent, parallel-safe actions). Each action
-   carries the failure-mode matrix: one row per operation, the failure mode, and the test that
-   catches it. A `.gitkeep`-only `actions/` is not a finished How.
-3. Write `checklist.md` covering every action.
-4. Dispatch the plan reviewer (boot 1) with `plastic-intent-executing`'s
-   `plan-reviewer-prompt.md`, the spawn preamble, and the intent directory. Fold every finding
-   into the spec, the matrix, and the tests; record what was dropped and why in the action
-   file's review fold. A REVISE verdict is folded and not re-reviewed unless a finding changes
-   a decision.
-5. Print `ruby ~/.plastic/scripts/report-screen plan <intent_dir>` as the first characters of
-   the reply, nothing before it, no fence, before dispatching the executor (see
-   `references/human-report-contract.md` for the full binding table). It informs; it does not wait.
+For a graph delivery, How is `graph.md` itself: no `plan.md`, no separate plan review (D1,
+341). For work with no graph: write `plan.md` (numbered steps) and at least one real
+`actions/ACTION_N.md` carrying the failure-mode matrix (one row per operation, the failure
+mode, the test that catches it; a `.gitkeep`-only `actions/` is not a finished How), then
+`checklist.md` covering every action. The plan reviewer is optional, not a required step:
+when the delivery warrants review before code, dispatch it (boot 1) with
+`plastic-intent-executing`'s `plan-reviewer-prompt.md`, the spawn preamble, and the intent
+directory, apply every finding to the spec, the matrix, and the tests, and record what was
+dropped and why in the action file's review notes. A REVISE verdict is applied and not
+re-reviewed unless a finding changes a decision.
+
+Print `ruby ~/.plastic/scripts/report-screen plan <intent_dir>` as the first characters of
+the reply, nothing before it, no fence, before dispatching the executor (see
+`references/human-report-contract.md` for the full binding table). It informs; it does not wait.
 
 Then Exec.
 
 ## Exec (the executor)
 
-1. Dispatch `plastic-executor` (boot 2) through `plastic-intent-executing` with the whole
-   consolidated action pasted in: the spec decisions, the matrix, the checklist items, the
-   worktree path from the preamble. Tests first: the executor commits the matrix's tests red,
-   then builds, then drives the full suite green.
-2. Read its return by code: DONE or DONE_WITH_CONCERNS proceeds; NEEDS_CONTEXT re-dispatches
-   with the missing context; BLOCKED stops under the error procedure.
-3. Tick the checklist as items land (the executor does this); verify tick-versus-diff against the diff. A mismatch is a review finding, not a lead cleanup.
+For a graph delivery, `runner step` prints the spawn block for the next ready node; paste it
+into the Agent tool, verbatim. For work with no graph, dispatch `plastic-executor` (boot 2)
+through `plastic-intent-executing` with the whole consolidated action pasted in.
+
+1. Read the executor's return by code: DONE or DONE_WITH_CONCERNS proceeds; NEEDS_CONTEXT
+   re-dispatches with the missing context; BLOCKED stops under the error procedure.
+2. Tick the checklist as items land (the executor does this); verify tick-versus-diff against
+   the diff. A mismatch is a review finding, not a lead cleanup.
 
 ## Review by risk (boot 3, only when a rule fires)
 
@@ -224,13 +221,14 @@ holds, each checkable from disk with no judgment; otherwise the green suite is t
 1. `git diff --name-only <red-commit>..HEAD` touches a path on the risk list in
    `references/agent-architecture.md` (hooks, the lock, the arming module, the installer, a
    release file).
-2. A row of any `actions/ACTION_N.md` failure-mode matrix names a test file that is not in that
-   diff, or a test the green run did not execute.
+2. A row of any failure-mode matrix (an `actions/ACTION_N.md` or a `nodes/*.md` file) names a
+   test file that is not in that diff, or a test the green run did not execute.
 3. The executor's completion report carries a status other than `delivered`, or a non-empty
    `deviations` or `blockers` field.
 
 The reviewer returns a pass or a list of fixes; the executor (re-dispatched) applies them, then
-the suite runs once more.
+the suite runs once more. On a graph, the risk rule maps onto the verify nodes named in
+`graph.md`'s decisions; at most one review-fix round, never more.
 ## Project Creation
 
 If the plan calls for creating a new project, determine the path from `~/.plastic/config.yml`