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

package/scripts/hook-savepoint

@@ -15,12 +15,31 @@
 require "json"
 require_relative "lib/session_ledger"
 require_relative "lib/handoff"
+require_relative "lib/active_delivery"
 
 MESSAGE = "PLASTIC SAVEPOINT - context is being compacted. The hand-off for this " \
           "session is written in today's day ledger " \
           "(store/.sessions/<day>/handoff--<session>.md). " \
           "After compaction say continue to resume from it."
 
+# The intent this session is delivering, resolved through the same walk the
+# Stop gate uses (row 4.38): read-config's project_roots, plus the global
+# store, glob for a live delivery.lock this session holds. Never raises
+# (ActiveDelivery.resolve rescues its own reads); a lookup failure just
+# means the Runner section is omitted, never that the hand-off is lost.
+def resolve_intent(plastic_home, session_id, read_config_path)
+  return nil if session_id.strip.empty?
+
+  global_store = File.join(plastic_home, "store")
+  roots_raw = IO.popen({ "PLASTIC_HOME" => plastic_home }, [read_config_path, "project_roots"],
+                       err: File::NULL, &:read).to_s.strip
+  project_roots = roots_raw.empty? ? [] : Array(JSON.parse(roots_raw))
+  project_roots = project_roots.map { |root| File.expand_path(root.to_s) }
+  ActiveDelivery.resolve(global_store: global_store, project_roots: project_roots, session: session_id)
+rescue StandardError
+  nil
+end
+
 written = nil
 begin
   plastic_home = ARGV[0].to_s
@@ -30,11 +49,14 @@ begin
   session_id = payload["session_id"].to_s
 
   unless plastic_home.empty? || session_id.strip.empty?
-    store = File.join(File.expand_path(plastic_home), "store")
+    home = File.expand_path(plastic_home)
+    store = File.join(home, "store")
     session = SessionLedger.short_session_id(session_id, nil)
     day = Handoff.day_for(store, session, today: SessionLedger.day_id)
+    read_config_path = File.expand_path("read-config", __dir__)
+    intent = resolve_intent(home, session_id, read_config_path)
     written = Handoff.write(store: store, day: day, session: session, trigger: "precompact",
-                            templates: File.expand_path("../templates", __dir__))
+                            templates: File.expand_path("../templates", __dir__), intent: intent)
   end
 rescue StandardError, JSON::ParserError
   nil

package/scripts/hook-session-start

@@ -14,6 +14,9 @@ require_relative "lib/doctor_core"
 require_relative "lib/session_ledger"
 require_relative "lib/day_summary"
 require_relative "lib/packet_wrapper"
+require_relative "lib/active_delivery"
+require_relative "lib/runner_core"
+require_relative "lib/runner_watch"
 
 index_path, plastic_home, mode, plugin_root = ARGV
 exit 0 unless index_path && plastic_home && mode
@@ -246,6 +249,43 @@ begin
     # Any failure (timeout, missing binary, parse error) — stay silent, never crash.
   end unless subagent_session
 
+  # --- Delivery watch (intent 340a, G7b, n3, graph.md D10) ---
+  # One unrecorded tick (record: false: reclaim and classify, no snapshot,
+  # no record line, so boot never advances a quiet count) per intent
+  # ActiveDelivery.candidate_intent_dirs finds, naming every stalled or
+  # done_unreported one in a single line, nothing when there are none. The
+  # whole block is one guarded unit, like the QMD block above it: a raise or
+  # a hang on any one candidate must add nothing rather than name only the
+  # candidates seen before the failure, so the line a boot does print is
+  # never a partial one.
+  begin
+    Timeout.timeout(2) do
+      roots_raw = IO.popen({ "PLASTIC_HOME" => plastic_home }, [read_config, "project_roots"],
+                            err: File::NULL, &:read).to_s.strip
+      project_roots = roots_raw.empty? ? [] : Array(JSON.parse(roots_raw))
+      project_roots = project_roots.map { |root| File.expand_path(root.to_s) }
+
+      attention = []
+      ActiveDelivery.candidate_intent_dirs(global_store: store_dir, project_roots: project_roots).uniq.each do |dir|
+        watch_context = RunnerCore.context(intent_dir: dir)
+        result = RunnerWatch.tick(watch_context, record: false)
+        next unless %w[stalled done_unreported].include?(result[:class])
+
+        watch_intent_id = File.basename(dir).split("--").first
+        if result[:class] == "stalled"
+          blocker = Array(result[:blockers]).first
+          attention << (blocker ? "#{watch_intent_id} stalled (#{blocker})" : "#{watch_intent_id} stalled")
+        else
+          attention << "#{watch_intent_id} done_unreported"
+        end
+      end
+      parts << "PLASTIC watch: #{attention.join(', ')}" if attention.any?
+    end
+  rescue Exception
+    # Any failure or timeout (a malformed intent directory, a hung tick) -
+    # stay silent, never crash boot.
+  end unless subagent_session
+
   # --- Project (or global) banner with its active intent ---
   # The one piece of intent context a live boot still carries: which store
   # is live, and which intent (if any) is active in it (intent 341, G8, D4).

package/scripts/hook-stop

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# hook-stop (intent 340b, G7c, n4, D5): the Stop hook body. Reads the harness
+# payload from stdin, gathers the runtime config StopGate needs, and asks it
+# whether this session may stop. Prints Claude Code's Stop block schema on
+# stdout only when the answer is block; a permit prints nothing at all.
+# Registration is static (hooks/hooks.json, settings.json) - this launcher
+# always installs - and the decision is runtime, off by default
+# (runner.stop_hook defaults false), so the owner flips continuation on or
+# off by editing config with no reinstall. Every error permits: always
+# exits 0, never raises out to the harness.
+#
+# Usage: hook-stop <plastic_home>   (stdin: the hook JSON)
+
+require "json"
+require_relative "lib/stop_gate"
+
+plastic_home = ARGV[0]
+exit 0 if plastic_home.nil? || plastic_home.empty?
+
+def read_config_value(key, home, read_config)
+  IO.popen({ "PLASTIC_HOME" => home }, [read_config, key], err: File::NULL, &:read).to_s.strip
+rescue StandardError
+  ""
+end
+
+begin
+  raw = $stdin.tty? ? "" : $stdin.read.to_s
+  payload = raw.strip.empty? ? {} : JSON.parse(raw)
+  payload = {} unless payload.is_a?(Hash)
+
+  home = File.expand_path(plastic_home)
+  global_store = File.join(home, "store")
+  read_config = File.expand_path("read-config", __dir__)
+
+  config_stop_hook = read_config_value("runner.stop_hook", home, read_config)
+  roots_raw = read_config_value("project_roots", home, read_config)
+  project_roots =
+    begin
+      roots_raw.strip.empty? ? [] : Array(JSON.parse(roots_raw))
+    rescue JSON::ParserError
+      []
+    end
+  project_roots = project_roots.map { |root| File.expand_path(root.to_s) }
+
+  session = payload["session_id"].to_s
+
+  result = StopGate.decide(payload: payload, config_stop_hook: config_stop_hook, session: session,
+                           global_store: global_store, project_roots: project_roots)
+
+  puts JSON.generate("decision" => "block", "reason" => result[:reason]) if result[:block]
+rescue StandardError
+  nil
+end
+exit 0

package/scripts/lib/active_delivery.rb

@@ -0,0 +1,61 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "lock"
+
+# ActiveDelivery (intent 340b, G7c, n4, D10): which intent a session is
+# delivering. A lock is a file inside an intent directory, and intents live
+# under the global store or under any configured project's store, so
+# answering "which intent" needs a walk, not an index the way node_ids.rb
+# indexes ids: one Dir.glob per configured root (plus one for the global
+# store) and one JSON parse per candidate lock file. No validator, no graph
+# rebuild, nothing else touches disk. Shared by StopGate (the fourth arming
+# condition needs to know the lock's run_mode) and Handoff (the Runner
+# section needs to know which intent's runner-step.last to render).
+#
+# Pure and dependency-injected: every call takes explicit paths; nothing
+# here reads ENV, shells out, or raises across its own boundary.
+module ActiveDelivery
+  module_function
+
+  # resolve(global_store:, project_roots:, session:, ttl:, now:) -> intent_dir or nil.
+  # Nil for zero matches or more than one: a session holding two live locks
+  # at once is a state nothing downstream may guess through (row 4.25).
+  def resolve(global_store:, project_roots:, session:, ttl: Lock::TTL_SECONDS, now: Time.now)
+    held = candidate_intent_dirs(global_store: global_store, project_roots: project_roots)
+           .uniq
+           .select { |dir| held_live?(dir, session: session, ttl: ttl, now: now) }
+    held.size == 1 ? held.first : nil
+  end
+
+  # Every intent directory under the global store or a configured project
+  # root that carries a delivery.lock file, unparsed. One Dir.glob per root
+  # (row 4.27): the global store's intents sit directly under store/, a
+  # project root's intents sit two levels down, under <root>/<slug>/store/.
+  def candidate_intent_dirs(global_store:, project_roots:)
+    dirs = []
+    dirs.concat(Dir.glob(File.join(global_store.to_s, "*", "delivery.lock"))) unless blank?(global_store)
+    Array(project_roots).each do |root|
+      next if blank?(root)
+
+      dirs.concat(Dir.glob(File.join(root.to_s, "*", "store", "*", "delivery.lock")))
+    end
+    dirs.map { |lock_path| File.dirname(lock_path) }
+  end
+
+  # Live and held by this session: a fresh (non-expired) lock whose owner or
+  # delegate list names this session. A torn or unparseable lock is skipped,
+  # never raised (row 4.26): a module a hook depends on must fail as quietly
+  # as the hook itself does.
+  def held_live?(intent_dir, session:, ttl:, now:)
+    return false unless Lock.fresh?(intent_dir, ttl: ttl, now: now)
+
+    Lock.holds?(intent_dir, session: session)
+  rescue StandardError
+    false
+  end
+
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+end

package/scripts/lib/agent_models.rb

@@ -10,9 +10,18 @@
 module AgentModels
   # Claude Code aliases only (never pinned ids, never Fable). Keys are the agent
   # file basenames without the `.md` extension.
+  # The three per-kind node agents (intent 340b, G7c, n2), dispatched by
+  # HarnessAdapter::AGENT_TYPE_BY_KIND. work and research resolve the
+  # executor tier, verify the advisor tier, mirroring RunnerPolicy's
+  # model_role split (327 D12): work and research run on plastic-executor's
+  # own tier, verify on the same tier plastic-advisor's imitation
+  # (plastic-faux-advisor) ships, never the cheap tier.
   TIER_DEFAULTS = {
     "plastic-enforcer" => "opus",
-    "plastic-executor" => "sonnet"
+    "plastic-executor" => "sonnet",
+    "plastic-node-work" => "sonnet",
+    "plastic-node-verify" => "opus",
+    "plastic-node-research" => "sonnet"
   }.freeze
 
   # The two advisor agents (intent 185 final design): plastic-advisor (the real

package/scripts/lib/codex_adapter.rb

@@ -0,0 +1,197 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+require "timeout"
+require "tmpdir"
+require_relative "runner_policy"
+
+# CodexAdapter (intent 340b, G7c, n6): the argv `codex exec` needs for one
+# node's kind, and the mechanics of running it once - a bounded subprocess
+# whose stdin carries the packet, whose stdout and `--output-last-message`
+# file are the only two places a return can come from, and whose timeout
+# kills the whole process group rather than one pid.
+#
+# Pure where it can be: sandbox_mode, git_dir_for_worktree, add_dir_args and
+# build_argv touch nothing but the filesystem read they are explicitly given
+# (the worktree's own `.git` file), never a git call and never a guess at a
+# repository root. #execute is the one place this module actually spawns a
+# child process; scripts/node-run is the only caller.
+module CodexAdapter
+  module_function
+
+  # Verify and research get NO write access at all (spec D9): read-only, no
+  # `--add-dir`. Everything else - work, and any kind this table has never
+  # heard of - gets the widest treatment, matching RunnerPolicy's own
+  # unknown-kind-falls-back-to-work rule (matrix row 6.10).
+  READ_ONLY_KINDS = %w[verify research].freeze
+
+  def sandbox_mode(kind)
+    READ_ONLY_KINDS.include?(kind.to_s) ? "read-only" : "workspace-write"
+  end
+
+  # The repository's OWN `.git` directory, derived from `worktree`'s `.git`
+  # FILE (a git worktree never carries a real `.git` directory of its own -
+  # spec) rather than any guess at how many path segments separate a
+  # worktree from its repo (matrix row 6.6). `.git` reads
+  # `gitdir: <repo>/.git/worktrees/<name>`; two directories up from that
+  # target is the repository's real `.git`. Returns nil when `worktree` is
+  # not a git worktree at all (no `.git` file, or `.git` is a directory,
+  # meaning `worktree` is a repository's own primary checkout) - callers
+  # treat that as "no `--add-dir` to add", never as a reason to guess.
+  def git_dir_for_worktree(worktree)
+    gitfile = File.join(worktree.to_s, ".git")
+    return nil unless File.file?(gitfile)
+
+    content = File.read(gitfile)
+    m = content.match(/\Agitdir:\s*(.+?)\s*\z/m)
+    return nil unless m
+
+    worktrees_entry = File.expand_path(m[1], worktree.to_s)
+    File.dirname(File.dirname(worktrees_entry))
+  end
+
+  # [] for a read-only kind (matrix row 6.4): `-C` already makes the
+  # worktree writable, and `--add-dir` on top of `--sandbox read-only` would
+  # contradict the sandbox mode itself. Exactly one `--add-dir`, the
+  # repository's own `.git`, for every other kind (matrix row 6.5) - nil
+  # when the worktree's own gitdir pointer cannot be resolved, so a caller
+  # handed a plain (non-worktree) directory never gets a bogus argument.
+  def add_dir_args(kind:, worktree:)
+    return [] if READ_ONLY_KINDS.include?(kind.to_s)
+
+    git_dir = git_dir_for_worktree(worktree)
+    git_dir ? ["--add-dir", git_dir] : []
+  end
+
+  # The whole `codex exec` argv for one node (matrix rows 6.1-6.9): `-C` at
+  # the worktree given (row 6.8), the sandbox mode and `--add-dir` this
+  # kind's row calls for and nothing else (row 6.7 - never the intent
+  # worktree, never `~/.plastic`), `--output-last-message` at the path the
+  # caller names, and a bare `-` so the prompt is read from stdin (row 6.9) -
+  # the packet itself never rides in this array.
+  def build_argv(kind:, worktree:, output_last_message:)
+    [
+      "codex", "exec",
+      "-C", worktree.to_s,
+      "--sandbox", sandbox_mode(kind),
+      *add_dir_args(kind: kind, worktree: worktree),
+      "--output-last-message", output_last_message.to_s,
+      "-",
+    ]
+  end
+
+  # matrix row 6.23: the wall-clock bound comes from the KIND's own lease
+  # length (RunnerPolicy.lease_minutes), never one shared constant - a long
+  # `work` build must not be capped as tightly as a quick `verify` pass.
+  def timeout_seconds(kind)
+    RunnerPolicy.lease_minutes(kind) * 60
+  end
+
+  # The return text (matrix rows 6.18/6.19): `output_last_message_path`'s
+  # own content when it exists and is non-blank (row 6.18 - stdout is never
+  # even inspected on this path), else the last YAML document found in
+  # `stdout` (row 6.19), else nil (no return anywhere - row 6.20 is the
+  # caller's problem, not this method's).
+  def read_return(output_last_message_path:, stdout:)
+    from_file = file_present_content(output_last_message_path)
+    return from_file unless from_file.nil?
+
+    stdout_fallback(stdout)
+  end
+
+  # The LAST YAML document in `text` that parses to a mapping, or nil when
+  # none does (row 6.20's other half). Documents are separated the ordinary
+  # YAML way, a line holding only `---`; a stream with no such separator at
+  # all is treated as one candidate document. Every candidate is tried from
+  # the end, so three documents (one row names explicitly) still resolve to
+  # the last one, and prose or a fragment that never parses to a mapping is
+  # skipped rather than returned as the "document".
+  def stdout_fallback(text)
+    return nil if text.to_s.strip.empty?
+
+    segments = text.to_s.split(/^---[ \t]*$/m).map(&:strip).reject(&:empty?)
+    segments = [text.to_s.strip] if segments.empty?
+
+    segments.reverse_each do |segment|
+      return segment if safe_yaml(segment).is_a?(Hash)
+    end
+    nil
+  end
+
+  # Runs `argv` once, feeding `stdin_data` on stdin through a scratch file
+  # (never a pipe - the same "never deadlock the read side" reasoning
+  # HookReplay.run_bounded already carries), bounded to `timeout_seconds`.
+  # `argv`'s own child becomes its own process group (`pgroup: true`) so a
+  # timeout can kill every child `codex exec` spawned along the way, not
+  # just the pid this call started (matrix row 6.24) - `codex exec` itself
+  # spawns shells for the commands it runs, and those would otherwise
+  # outlive a plain `Process.kill` on the parent alone, holding the
+  # worktree.
+  #
+  # Returns {exit_code:, timed_out:, stdout:, message:}. `message` is
+  # #read_return's result, computed only when the call did not time out - a
+  # timed-out child's partial output is never trusted (matrix row 6.22).
+  def execute(argv, stdin_data:, timeout_seconds:, output_last_message_path:)
+    Dir.mktmpdir("plastic-node-run-") do |scratch|
+      in_path = File.join(scratch, "stdin")
+      out_path = File.join(scratch, "stdout")
+      err_path = File.join(scratch, "stderr")
+      File.binwrite(in_path, stdin_data.to_s)
+
+      pid = Process.spawn(*argv.map(&:to_s), in: in_path, out: out_path, err: err_path, pgroup: true)
+      timed_out = false
+      exit_code =
+        begin
+          Timeout.timeout(timeout_seconds) do
+            Process.wait(pid)
+            $?.exitstatus
+          end
+        rescue Timeout::Error
+          timed_out = true
+          kill_group(pid)
+          nil
+        end
+
+      stdout = File.exist?(out_path) ? File.read(out_path) : ""
+      message = timed_out ? nil : read_return(output_last_message_path: output_last_message_path, stdout: stdout)
+
+      { exit_code: exit_code, timed_out: timed_out, stdout: stdout, message: message }
+    end
+  end
+
+  # --- internals ---------------------------------------------------------------
+
+  def file_present_content(path)
+    return nil if path.nil? || !File.exist?(path)
+
+    content = File.read(path)
+    content.strip.empty? ? nil : content
+  end
+  private_class_method :file_present_content
+
+  def safe_yaml(text)
+    YAML.safe_load(text, aliases: false, permitted_classes: [])
+  rescue Psych::Exception, ArgumentError
+    nil
+  end
+  private_class_method :safe_yaml
+
+  # Kills the whole process GROUP `pid` leads, not just `pid` itself (matrix
+  # row 6.24): a negative pid signals the group. Rescued and reaped exactly
+  # like HookReplay.kill_and_reap - a process that exited in the race
+  # between the timeout firing and this call raises Errno::ESRCH on the kill
+  # or Errno::ECHILD on the wait, neither of which should ever propagate.
+  def kill_group(pid)
+    Process.kill("KILL", -pid)
+  rescue StandardError
+    nil
+  ensure
+    begin
+      Process.wait(pid)
+    rescue StandardError
+      nil
+    end
+  end
+  private_class_method :kill_group
+end

package/scripts/lib/doctor_core.rb

@@ -27,11 +27,16 @@ class Doctor
     "hermes" => { name: "Hermes",      dir: File.join(Dir.home, ".hermes") },
   }.freeze
 
-  # The Claude events hooks_registered expects in settings.json: the six-event map of
+  # The Claude events hooks_registered expects in settings.json: the eight-event map of
   # cut-inventory 3b (intent 309 added SessionEnd, registered for close since intent 301;
-  # intent 316a added MessageDisplay, registered for message-display, Claude only).
+  # intent 316a added MessageDisplay, registered for message-display, Claude only; intent
+  # 355 added PreToolUse, registered for call-budget, Claude only; intent 340b added Stop,
+  # registered for stop, Claude only). Stop's registration is static (D5/D7) even though
+  # its runtime arm defaults off (D9, runner.stop_hook), so an install missing it is
+  # exactly as broken as one missing PreCompact, and this list keeps hooks_registered and
+  # hooks_match_registry agreeing on that (row 4.32).
   CLAUDE_HOOK_EVENTS = %w[SessionStart PreToolUse PreCompact PostToolUse UserPromptSubmit SessionEnd
-                          MessageDisplay].freeze
+                          MessageDisplay Stop].freeze
 
   # Launchers the installer places in the agent's hooks dir that are NOT hooks
   # (intent 204): plastic-statusline is the settings["statusLine"] command, wired

package/scripts/lib/engine_permissions.rb

@@ -0,0 +1,88 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# EnginePermissions: the engine deny rule (intent 340b, G7c, n3). A permissions.deny
+# block merged into settings.json at install so the engine directories are not
+# editable by a dispatched agent (C25's self-preservation half).
+#
+# Claude Code accepts a Write(...) path rule and never consults it: Edit(...) is the
+# rule that covers Write, MultiEdit and NotebookEdit. Every entry below names Edit,
+# never Write, and every entry ends in /** because a bare directory path matches the
+# directory itself, not the files under it.
+#
+# This is a second ownership mechanism, deliberately not a reuse of HookRegistry's
+# merge, which knows its own entries by a plastic- launcher basename inside a command
+# string. A deny entry is a bare string with no marker in it, so ownership here is
+# exact-string membership in ENTRIES. The consequence is deliberate: an entry the
+# owner has edited no longer matches the frozen string, so it is the owner's from
+# that point on - the merge appends Plastic's own alongside it, and removal leaves
+# the edited one in place untouched.
+#
+# Pure functions only: no file I/O here. InstallerCore#merge_engine_permissions and
+# #remove_engine_permissions own the read-modify-write against settings.json,
+# mirroring the split HookRegistry keeps from merge_claude_hooks.
+module EnginePermissions
+  module_function
+
+  ENTRIES = [
+    "Edit(~/.plastic/scripts/**)",
+    "Edit(~/.plastic/skills/**)",
+    "Edit(~/.plastic/hooks/**)",
+    "Edit(~/.plastic/templates/**)",
+  ].freeze
+
+  # Returns a new settings hash with ENTRIES merged into permissions.deny, appended
+  # (never duplicated) alongside whatever is already there. Survives a permissions
+  # or deny value that is not the shape expected (row 3.12): a non-Hash permissions
+  # value or a non-Array deny value is replaced rather than raised on. Never
+  # mutates the argument.
+  def merge_into(settings)
+    settings = settings.is_a?(Hash) ? settings.dup : {}
+
+    permissions = settings["permissions"]
+    permissions = permissions.is_a?(Hash) ? permissions.dup : {}
+
+    deny = permissions["deny"]
+    deny = deny.is_a?(Array) ? deny.dup : []
+
+    ENTRIES.each { |entry| deny << entry unless deny.include?(entry) }
+
+    permissions["deny"] = deny
+    settings["permissions"] = permissions
+    settings
+  end
+
+  # Returns a new settings hash with exactly the ENTRIES strings removed from
+  # permissions.deny, leaving every other entry (the owner's own deny rules, and
+  # any Plastic entry the owner has since edited) untouched. Prunes the deny array
+  # once it is empty, and the whole permissions block once nothing else remains
+  # under it (row 3.10). A settings/permissions/deny shape that is not what is
+  # expected is left alone rather than raised on (row 3.12's uninstall side).
+  def remove_from(settings)
+    return settings unless settings.is_a?(Hash)
+
+    permissions = settings["permissions"]
+    return settings unless permissions.is_a?(Hash)
+
+    deny = permissions["deny"]
+    return settings unless deny.is_a?(Array)
+
+    settings = settings.dup
+    permissions = permissions.dup
+    deny = deny.reject { |entry| ENTRIES.include?(entry) }
+
+    if deny.empty?
+      permissions.delete("deny")
+    else
+      permissions["deny"] = deny
+    end
+
+    if permissions.empty?
+      settings.delete("permissions")
+    else
+      settings["permissions"] = permissions
+    end
+
+    settings
+  end
+end

package/scripts/lib/graph_edges.rb

@@ -4,11 +4,11 @@
 # GraphEdges (intent 334, n1): the shared `needs` syntax and cycle-path check
 # (327 D2r-D4r, D12r). Parses a "## Graph" section's edge lines into a node
 # set and an edge map, the one parser an intent's graph.md and a roadmap's
-# own ## Graph section both use unchanged (C1, fold A5): the same list-item
+# own ## Graph section both use unchanged (C1, review A5): the same list-item
 # grammar, the same root keyword, the same cycle walk. Deliberately loose
 # about what an id looks like - a roadmap id is numeric ("334", "340a"), a
 # node id carries a kind prefix ("n1") - the kind-prefix rule belongs to
-# NodeFile and WorkGraphValidator, never here (D12r, fold A6).
+# NodeFile and WorkGraphValidator, never here (D12r, review A6).
 #
 # Grammar (D2r/D3r): a list item shaped "- <id> needs <target> [<target>
 # ...]", ending at end of line. The single literal target "nothing" declares
@@ -18,7 +18,7 @@
 # all, "nothing" alongside other targets, or a target token carrying
 # sentence punctuation (a period, a colon, ...) rather than the loose
 # id-token charset, is an error naming the line, never a silently
-# mis-parsed edge or an invented node (fold A7).
+# mis-parsed edge or an invented node (review A7).
 #
 # Pure and side-effect-free; never raises across the boundary, matching the
 # Result-hash convention every library in scripts/lib/ follows.
@@ -30,7 +30,7 @@ module GraphEdges
   ROOT_TARGET = "nothing"
 
   # {nodes:, edges:, errors:} - nodes is the declared ids together with every
-  # id any edge targets (fold A5), in first-seen order; edges maps a declared
+  # id any edge targets (review A5), in first-seen order; edges maps a declared
   # id to its target ids (empty for a root); errors names each malformed
   # edge-shaped line. Prose lines contribute nothing and raise nothing.
   def parse(section_text)

package/scripts/lib/graph_file.rb

@@ -7,9 +7,9 @@ require_relative "atomic_write"
 # GraphFile (intent 334, n2): the four graph.md sections (## Goal,
 # ## Decisions, ## Graph, ## Status), the verify:-none directive, and the two
 # writers - write_status and append_decision. Both writers refuse a cyclic
-# graph and both go through AtomicWrite (fold D19r). Fence-aware everywhere a
+# graph and both go through AtomicWrite (review D19r). Fence-aware everywhere a
 # heading is located, so a fenced example carrying a fake "## " line never
-# splits or ends a real section (fold A8's sibling concern, applied to
+# splits or ends a real section (review A8's sibling concern, applied to
 # section boundaries rather than edge lines).
 module GraphFile
   module_function
@@ -19,8 +19,8 @@ module GraphFile
 
   # {ok:, goal:, decisions:, graph:, status:, verify:, errors:}. `graph` is
   # GraphEdges.parse's own Result hash, over the Graph section text with any
-  # verify:-none directive line stripped first (fold A8). A missing ## Graph
-  # section, or one that declares no nodes, is an error naming which (fold
+  # verify:-none directive line stripped first (review A8). A missing ## Graph
+  # section, or one that declares no nodes, is an error naming which (review
   # A10).
   def parse(path)
     return failure(["graph file not found: #{path}"]) unless File.exist?(path)