@zalom/plastic 2.0.0-alpha.2 → 2.0.0-alpha.20

package/scripts/lib/session_git.rb

@@ -207,11 +207,37 @@ module SessionGit
 
   # --- commit message ------------------------------------------------------------
 
-  # The first line of `summary`, truncated to MAX_SUBJECT_LENGTH characters,
-  # with no trailer (spec D5).
+  # The first line of `summary`, cut at the last word boundary at or before
+  # MAX_SUBJECT_LENGTH characters, falling back to the hard slice when no
+  # boundary exists at or before the limit (spec D6, amends spec 300 D5's
+  # unconditional `first_line[0, MAX_SUBJECT_LENGTH]`, which cut mid-word).
+  # A subject at or under the limit is returned unchanged. Post-execution
+  # review item 7: when the character immediately after the 72-char prefix
+  # is ITSELF a space, the prefix already ends exactly on a word boundary and
+  # needs no trimming at all -- checked before consulting `rindex`, because
+  # an earlier internal space inside the 72-char prefix would otherwise make
+  # `rindex` walk back past a whole trailing word that fit perfectly.
   def subject_for(summary)
     first_line = summary.to_s.split(/\r?\n/, 2).first.to_s.strip
-    first_line[0, MAX_SUBJECT_LENGTH]
+    return first_line if first_line.length <= MAX_SUBJECT_LENGTH
+
+    cut = first_line[0, MAX_SUBJECT_LENGTH]
+    return cut if first_line[MAX_SUBJECT_LENGTH] == " "
+
+    boundary = cut.rindex(" ")
+    boundary ? cut[0, boundary] : cut
+  end
+
+  # The commit body for `summary`/`subject` (spec D6): the full summary when
+  # `subject` is a cut-down copy of it, nil when the subject already carries
+  # the summary whole (no redundant body on a short, single-line summary).
+  # Post-execution review item 4: compares the STRIPPED raw summary, not the
+  # raw summary verbatim -- a summary with only trailing/leading whitespace
+  # around an otherwise-identical subject must not repeat the same sentence
+  # twice as a redundant body.
+  def body_for(summary, subject)
+    raw = summary.to_s
+    raw.strip == subject ? nil : raw
   end
 
   # --- git primitives (all use -C, never cwd) -------------------------------------
@@ -273,9 +299,11 @@ module SessionGit
     parts.each_cons(2).any? { |a, b| a == ".claude" && b == "worktrees" }
   end
 
-  def stage_and_commit(dir, subject, runner:)
+  def stage_and_commit(dir, subject, runner:, body: nil)
     runner.run("-C", dir, "add", "-A")
-    runner.run("-C", dir, "commit", "-m", subject)
+    args = ["-C", dir, "commit", "-m", subject]
+    args += ["-m", body] if body
+    runner.run(*args)
   end
 
   def short_sha(dir, runner:)
@@ -310,14 +338,16 @@ module SessionGit
 
     flow, flow_notes = load_flow(cwd: cwd, repo: repo, plastic_home: plastic_home, runner: runner)
     subject = subject_for(summary)
+    body = body_for(summary, subject)
 
     result =
       if flow["mode"] == "pull_request"
-        commit_pull_request(repo: repo, subject: subject, day: day, session: session,
+        commit_pull_request(repo: repo, subject: subject, body: body, day: day, session: session,
                              store: effective_store, flow: flow, branch_now: branch_now,
                              runner: runner, gh_runner: gh_runner)
       else
-        commit_direct(repo: repo, subject: subject, day: day, flow: flow, branch_now: branch_now, runner: runner)
+        commit_direct(repo: repo, subject: subject, body: body, day: day, flow: flow, branch_now: branch_now,
+                       runner: runner)
       end
 
     return result if flow_notes.empty?
@@ -331,7 +361,7 @@ module SessionGit
 
   # --- direct mode (spec D3) --------------------------------------------------------
 
-  def commit_direct(repo:, subject:, day:, flow:, branch_now:, runner:)
+  def commit_direct(repo:, subject:, day:, flow:, branch_now:, runner:, body: nil)
     return note("nothing to commit") unless dirty?(repo, runner: runner)
     return note("summary is empty after truncation: no commit") if blank?(subject)
 
@@ -351,10 +381,10 @@ module SessionGit
     end
 
     if branch_now == base || branch_now == session_branch
-      commit_on_session_branch(repo: repo, subject: subject, base: base,
+      commit_on_session_branch(repo: repo, subject: subject, base: base, body: body,
                                 session_branch: session_branch, branch_now: branch_now, runner: runner)
     else
-      commit_on_other_branch(repo: repo, subject: subject, branch_now: branch_now, runner: runner)
+      commit_on_other_branch(repo: repo, subject: subject, body: body, branch_now: branch_now, runner: runner)
     end
   end
 
@@ -367,7 +397,7 @@ module SessionGit
   # session branch. `current_branch` is re-read after the switch and used
   # for the commit message instead of trusting the branch this method
   # intended to reach.
-  def commit_on_session_branch(repo:, subject:, base:, session_branch:, branch_now:, runner:)
+  def commit_on_session_branch(repo:, subject:, base:, session_branch:, branch_now:, runner:, body: nil)
     unless branch_exists?(repo, session_branch, runner: runner)
       create = runner.run("-C", repo, "branch", session_branch, base.to_s)
       return note("could not create session branch #{session_branch}: #{diagnose(create)}") unless create.success?
@@ -383,11 +413,12 @@ module SessionGit
       return note("expected to be on #{session_branch} but the checkout is on #{actual_branch.inspect}")
     end
 
-    commit_and_push(dir: repo, push_dir: repo, subject: subject, from: actual_branch, base: base, runner: runner)
+    commit_and_push(dir: repo, push_dir: repo, subject: subject, body: body, from: actual_branch, base: base,
+                     runner: runner)
   end
 
-  def commit_on_other_branch(repo:, subject:, branch_now:, runner:)
-    res = stage_and_commit(repo, subject, runner: runner)
+  def commit_on_other_branch(repo:, subject:, branch_now:, runner:, body: nil)
+    res = stage_and_commit(repo, subject, runner: runner, body: body)
     return note("commit rejected by commit-msg hook: #{diagnose(res)}") unless res.success?
 
     sha = short_sha(repo, runner: runner)
@@ -398,8 +429,8 @@ module SessionGit
   # shared tail. A non-fast-forward push (spec D3, "base moved ahead
   # independently") stays a Note: the commit itself already landed on the
   # session branch.
-  def commit_and_push(dir:, push_dir:, subject:, from:, base:, runner:)
-    res = stage_and_commit(dir, subject, runner: runner)
+  def commit_and_push(dir:, push_dir:, subject:, from:, base:, runner:, body: nil)
+    res = stage_and_commit(dir, subject, runner: runner, body: body)
     return note("commit rejected by commit-msg hook: #{diagnose(res)}") unless res.success?
 
     sha = short_sha(dir, runner: runner)
@@ -414,7 +445,7 @@ module SessionGit
 
   # --- pull request mode (spec D4) ------------------------------------------------
 
-  def commit_pull_request(repo:, subject:, day:, session:, store:, flow:, branch_now:, runner:, gh_runner:)
+  def commit_pull_request(repo:, subject:, day:, session:, store:, flow:, branch_now:, runner:, gh_runner:, body: nil)
     return note("nothing to commit") unless dirty?(repo, runner: runner)
     return note("summary is empty after truncation: no commit") if blank?(subject)
 
@@ -439,7 +470,7 @@ module SessionGit
       return note("could not check out branch #{branch}: #{diagnose(switch)}") unless switch.success?
     end
 
-    res = stage_and_commit(repo, subject, runner: runner)
+    res = stage_and_commit(repo, subject, runner: runner, body: body)
     outcome =
       if res.success?
         pull_request_outcome(repo: repo, subject: subject, branch: branch, base: base, gh_runner: gh_runner, runner: runner)

package/scripts/lib/session_ledger.rb

@@ -29,6 +29,10 @@ module SessionLedger
 
   SESSIONS_DIR = ".sessions"
   TMP_DIR = ".tmp"
+  # Named here, not in a CLI, so a caller can reference the key without the
+  # literal harness-branded env var name appearing in its own source (a few
+  # scripts are guarded against naming a harness at all).
+  SESSION_ID_ENV_KEY = "CLAUDE_CODE_SESSION_ID"
   DAY_ID = /\A\d{8}\z/
   EVENTS = %w[Item Done Note]
   STATES = { pending: "~", open: " ", done: "x", moved: ">", dropped: "-", promoted: "^" }.freeze
@@ -186,6 +190,130 @@ module SessionLedger
     "#{collapsed[0, 197]}..."
   end
 
+  # --- capture_worthy? (spec D2, D7; supersedes 298 D2(c)) -------------------
+
+  # One complete top-level harness envelope tag block: "<name ...>...</name>".
+  # Non-greedy (.*?) so sibling blocks are each matched on their own rather
+  # than one match spanning from the first block's opening tag all the way to
+  # the LAST block's closing tag (post-execution review item 3: an envelope
+  # on both sides of real work, "<system-reminder>...</system-reminder>\nfix
+  # the parser\n<task-notification>...</task-notification>", must not be
+  # read as one giant envelope swallowing the work in the middle).
+  ENVELOPE_BLOCK_RE = /<([A-Za-z][\w-]*)(?:\s[^>]*)?>.*?<\/\1>/m
+  private_constant :ENVELOPE_BLOCK_RE
+
+  # The whole prompt, case- and whitespace-insensitively, and nothing else
+  # (rule 3, D2): a trigger word inside a longer real instruction ("continue
+  # the dashboard fix and then release") must not match this.
+  BARE_TRIGGERS = %w[continue auto].freeze
+  private_constant :BARE_TRIGGERS
+
+  # Words whose presence marks a prompt as actionable work (rule 4's escape
+  # hatch, D2's accept bias). Deliberately excludes common nouns that also
+  # read as everyday verbs in casual remarks (e.g. "release", "ship", "plan"):
+  # including them would make ordinary conversation about a past release or
+  # plan look like a work request. Matched with an optional inflection suffix
+  # (post-execution review BLOCKER): the bare stems alone missed "fixed",
+  # "updated", "added", "reviewed", "implemented" -- exactly the past-tense
+  # and -ing forms real work summaries use.
+  WORK_MARKER_WORDS = %w[
+    fix add remove delete update upgrade implement write build create refactor
+    debug investigate review test deploy commit merge revert rename configure
+    install migrate document generate draft resolve help need want make change
+    setup
+  ].freeze
+  private_constant :WORK_MARKER_WORDS
+
+  WORK_MARKER_PHRASES = [
+    "can you", "could you", "would you", "let's", "let us", "set up", "look into", "figure out",
+  ].freeze
+  private_constant :WORK_MARKER_PHRASES
+
+  WORK_MARKER_RE = /\b(?:#{WORK_MARKER_WORDS.join("|")})(?:s|d|ed|ing)?\b/i
+  private_constant :WORK_MARKER_RE
+
+  # A first word that reads as an interrogative opener, checked case-
+  # insensitively against the prompt's first whitespace-separated token.
+  # Post-execution review BLOCKER: trimmed from the original, wider list
+  # (which also carried "how", "when", "where", "was", "were", "do", "did",
+  # "will", "shall", "should") down to words that open a genuine QUESTION at
+  # least as often as an ordinary command or request. Measured against 43
+  # invented and 27 real day-ledger prompts: the dropped words open ordinary
+  # work requests ("do the release now...", "when you are done, tag the
+  # release...", "will you push that branch...", "should I bump the version
+  # files...") far more often than they open a bare question worth rejecting.
+  QUESTION_STARTERS = %w[
+    what why who whom whose which is are am does can could would
+  ].freeze
+  private_constant :QUESTION_STARTERS
+
+  # A narrow set of retrospective-remark shapes ("that release went smoother
+  # than the last one"): comparative or evaluative observations about how
+  # something already went. Deliberately narrow (D2's accept bias): a broad
+  # "any declarative sentence with no recognized verb" rule would also catch
+  # ordinary work summaries like "harness text wins the pending line", which
+  # must stay accepted.
+  REMARK_PATTERNS = [
+    /\bwent\s+\w+\s+than\b/i,
+    /\bwent\s+(?:well|badly|smoothly|great|poorly|terribly)\b/i,
+  ].freeze
+  private_constant :REMARK_PATTERNS
+
+  # True iff nothing but harness envelope tag block(s) -- and whitespace --
+  # remain once every complete top-level block is stripped out. A prompt
+  # that is one envelope alone, or several envelopes with no other content,
+  # matches; a prompt carrying real work anywhere outside an envelope (before,
+  # after, or between several of them) does not.
+  def whole_prompt_envelope?(stripped)
+    stripped.gsub(ENVELOPE_BLOCK_RE, "").strip.empty?
+  end
+
+  def bare_trigger?(stripped)
+    BARE_TRIGGERS.include?(stripped.downcase)
+  end
+
+  def work_marker?(text)
+    return true if WORK_MARKER_RE.match?(text)
+
+    downcased = text.downcase
+    WORK_MARKER_PHRASES.any? { |p| downcased.include?(p) }
+  end
+
+  def interrogative?(stripped)
+    return true if stripped.end_with?("?")
+
+    first_word = stripped.split(/\s+/).first.to_s.downcase.gsub(/[^a-z]/, "")
+    QUESTION_STARTERS.include?(first_word)
+  end
+
+  def bare_remark?(stripped)
+    REMARK_PATTERNS.any? { |re| re.match?(stripped) }
+  end
+
+  # Internal helpers only: #capture_worthy? is the sole public contract
+  # (post-execution review item 9).
+  private_class_method :whole_prompt_envelope?, :bare_trigger?, :work_marker?, :interrogative?, :bare_remark?
+
+  # Whether `prompt` earns a pending checklist line (spec D2). Bias is
+  # ACCEPT: this rejects only on four named rules -- the 10-char floor (on
+  # its own collapsed copy), a whole-prompt harness envelope, a bare
+  # continue/auto trigger, and an interrogative or bare-remark prompt
+  # carrying no work marker -- and accepts everything else, including a
+  # work-shaped question and an envelope followed by real work. Takes the
+  # RAW prompt (not the sanitized/truncated line text) so rule 2 sees the
+  # prompt's true first character and multi-line shape.
+  def capture_worthy?(prompt)
+    raw = prompt.to_s
+    return false if sanitize_summary(raw).length < 10
+
+    stripped = raw.strip
+    return false if whole_prompt_envelope?(stripped)
+    return false if bare_trigger?(stripped)
+    return false if !work_marker?(stripped) && (interrogative?(stripped) || bare_remark?(stripped))
+
+    true
+  end
+
   # One LF-terminated checklist line, byte exact per spec D5. The state
   # marker is fixed width across all three states, which is what lets a later
   # promote or tick be a one-byte write at a known offset.

package/scripts/lib/verify_intent.rb

@@ -70,6 +70,10 @@ module VerifyIntent
     lines.concat(diffstat_lines)
     checks[:diffstat] = diffstat_check
 
+    report_lines_out, report_check = run_report_lines_check(intent_dir: intent_dir)
+    lines.concat(report_lines_out)
+    checks[:report] = report_check
+
     if Worktree.blank?(suite)
       checks[:suite] = { status: "skipped" }
     else
@@ -235,6 +239,35 @@ module VerifyIntent
     end
   end
 
+  # --- check: the Report savepoint lines (intent 331f, F17) ------------------------
+
+  REPORT_LINE_RE = /\A(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ)\s{2,}(\S+)\s{2,}(.+?)\s*\z/.freeze
+
+  # Every `Report`-kind savepoint line for this intent, oldest first: [timestamp, text].
+  # Never fails or gates anything (D3: the diffstat check already prints a summary block,
+  # this folds into the same verdict so verify-intent surfaces them too) - a delivery with
+  # no Report line is visible to `doctor`'s intent_reports_printed_check instead.
+  def report_lines(intent_dir)
+    path = File.join(intent_dir, "savepoint.md")
+    return [] unless File.exist?(path)
+
+    File.readlines(path).filter_map do |line|
+      m = line.strip.match(REPORT_LINE_RE)
+      next nil unless m && m[2] == "Report"
+      [m[1], m[3]]
+    end
+  end
+
+  def run_report_lines_check(intent_dir:)
+    entries = report_lines(intent_dir)
+    if entries.empty?
+      [["report lines: none recorded"], { status: "pass", lines: [] }]
+    else
+      lines = ["report lines:"] + entries.map { |ts, text| "#{ts}  Report  #{text}" }
+      [lines, { status: "pass", lines: entries }]
+    end
+  end
+
   # --- check 4: the optional suite --------------------------------------------------
 
   # The supplied command is very likely a ruby command, so it is spawned with RUBYOPT

package/scripts/lib/work_graph_validator.rb

@@ -0,0 +1,201 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "graph_file"
+require_relative "graph_edges"
+require_relative "node_file"
+require_relative "action_graph_shim"
+
+# WorkGraphValidator (intent 334, n4): the in-batch reader over one intent's
+# graph.md and nodes/ - 327's rule for budget, files, and the decision and
+# research kinds (fold A17). {ok:, missing:, errors:}, the same Result shape
+# ProjectValidator returns (fold B7). Named apart from
+# IntentValidator#validate_graph, which already exists for the KNOWLEDGE
+# graph and stays unrelated to this one under D40 (fold B9).
+#
+# Built over GraphFile, GraphEdges, and NodeFile only - never IntentValidator,
+# never ReportScreen. Every check accumulates into `errors` rather than
+# short-circuiting on the first one (fold: "the owner fixes one thing per
+# run").
+module WorkGraphValidator
+  module_function
+
+  def validate(intent_dir)
+    missing = []
+    errors = []
+
+    graph_path = File.join(intent_dir, "graph.md")
+    parsed = GraphFile.parse(graph_path)
+    errors.concat(parsed[:errors])
+
+    graph = parsed[:graph]
+    if graph.nil?
+      # G9 (intent 342, D6/D7/D12): a legacy intent that never got a
+      # graph.md still reads as a valid work graph, structurally, through
+      # the backward shim - but only when graph.md is genuinely absent.
+      # A graph.md that exists but is malformed (no "## Graph" section)
+      # must never fall through to the synthetic chain and hide its own
+      # error (D12's whole point). The fresh error list here is
+      # deliberate: `errors` above already holds the not-found error from
+      # `parsed[:errors]`, and reusing it would return ok: false for every
+      # legacy intent in the store.
+      if !File.exist?(graph_path) && ActionGraphShim.shape(intent_dir) == :actions
+        return validate_actions_shape(intent_dir)
+      end
+
+      missing << "graph.md ## Graph section"
+      return { ok: false, missing: missing, errors: errors }
+    end
+
+    nodes = graph[:nodes]
+    edges = graph[:edges]
+    declared_ids = edges.keys
+
+    # Intent-scope dangling check: every node must be declared with its own
+    # needs-line here (unlike a roadmap, which may have undeclared roots -
+    # that reconciliation is G4's, not this validator's).
+    (nodes - declared_ids).each { |id| errors << "needs target #{id.inspect} names no declared node" }
+
+    cyc = GraphEdges.cycle(edges)
+    errors << "cyclic graph, cannot validate: #{cyc.join(' > ')}" if cyc
+
+    node_paths = Dir.glob(File.join(intent_dir, "nodes", "*.md")).sort
+    parsed_nodes = {}
+    paths_by_id = Hash.new { |h, k| h[k] = [] }
+
+    node_paths.each do |path|
+      nf = NodeFile.parse(path)
+      nf[:errors].each { |e| errors << "#{File.basename(path)}: #{e}" }
+      id = nf[:node]
+      next unless id
+
+      paths_by_id[id] << path
+      parsed_nodes[id] ||= nf
+    end
+
+    paths_by_id.each do |id, paths|
+      next unless paths.length > 1
+
+      errors << "node id #{id.inspect} claimed by more than one file: #{paths.map { |p| File.basename(p) }.join(', ')}"
+    end
+
+    declared_ids.each do |id|
+      missing << "nodes/ file for #{id}" unless parsed_nodes.key?(id)
+      errors << "declared node #{id.inspect} has no node file under nodes/" unless parsed_nodes.key?(id)
+    end
+    parsed_nodes.each_key do |id|
+      errors << "node file for #{id.inspect} exists but ## Graph declares no such node" unless declared_ids.include?(id)
+    end
+
+    work_nodes = []
+    verify_nodes = []
+
+    declared_ids.each do |id|
+      nf = parsed_nodes[id]
+      next unless nf
+
+      case nf[:kind]
+      when "verify"
+        verify_nodes << id
+        errors << "verify node #{id.inspect} has no ## Criteria" unless has_section?(nf[:body], "## Criteria")
+      when "decision"
+        errors << "decision node #{id.inspect} has no ## Question with a question" unless has_nonblank_section?(nf[:body], "## Question")
+      when "research"
+        errors << "research node #{id.inspect} has no ## Deposit" unless has_section?(nf[:body], "## Deposit")
+      when "work"
+        work_nodes << id
+        errors << "work node #{id.inspect} has no ## Steps" unless has_section?(nf[:body], "## Steps")
+        errors << "work node #{id.inspect} has no ## Proven by" unless has_section?(nf[:body], "## Proven by")
+      end
+    end
+
+    above_trivial_bar = work_nodes.length >= 2
+    if above_trivial_bar
+      verify_directive = parsed[:verify]
+      directive_ok = verify_directive && !verify_directive[:reason].to_s.empty?
+
+      unless directive_ok
+        attached = verify_nodes.select { |vid| node_touches_graph?(vid, edges) }
+        if attached.empty?
+          errors << "two or more work nodes require a verify node attached to the graph, or a verify: none reason=<text> directive"
+        end
+      end
+
+      work_nodes.each do |id|
+        nf = parsed_nodes[id]
+        next unless nf
+
+        errors << "work node #{id.inspect} has no failure-mode matrix under a heading carrying its id" unless has_valid_matrix?(id, nf[:body])
+      end
+    end
+
+    verify_nodes.each do |id|
+      next if node_touches_graph?(id, edges)
+
+      errors << "verify node #{id.inspect} exists but no edge reaches it (attach it or drop it)"
+    end
+
+    { ok: errors.empty?, missing: missing, errors: errors }
+  end
+
+  # A node "touches" the graph when some edge involves it on either side:
+  # it targets something, or something targets it. A verify node declared
+  # with "needs nothing" and targeted by nothing is fully isolated (fold
+  # A13).
+  def node_touches_graph?(id, edges)
+    (edges[id] || []).any? || edges.values.any? { |targets| targets.include?(id) }
+  end
+
+  def has_section?(body, heading_text)
+    NodeFile.split_by_headings(body.to_s).any? { |heading, _| heading.strip == heading_text }
+  end
+
+  def has_nonblank_section?(body, heading_text)
+    NodeFile.split_by_headings(body.to_s).any? { |heading, section| heading.strip == heading_text && !section.strip.empty? }
+  end
+
+  def heading_tokens(heading)
+    heading.to_s.sub(/\A#+\s*/, "").split(/[^A-Za-z0-9]+/)
+  end
+
+  # The matrix table must sit under a heading whose tokens include the
+  # node's own id, and that heading must own at least one data row (fold
+  # A1 - the same table-owning rule report_screen's resolver uses, so a
+  # node's own Proven-by cell is never "not recorded" the moment it ships).
+  def has_valid_matrix?(id, body)
+    NodeFile.split_by_headings(body.to_s).any? do |heading, section|
+      heading_tokens(heading).include?(id) && NodeFile.table_rows(section).any?
+    end
+  end
+
+  # The structural check the synthetic (actions/-only) shape gets, and
+  # nothing more (D6): at least one node, unique ids, every needs target
+  # names a declared node, acyclic. Never the kind-section rules, the
+  # failure-mode matrix bar, or the verify-attachment bar - a legacy action
+  # file labels its headings "S1", or nothing at all, and was never asked
+  # to meet a bar written for a graph authored under 327.
+  def validate_actions_shape(intent_dir)
+    errors = []
+    graph = ActionGraphShim.view(intent_dir)[:graph] || { nodes: [], edges: {}, errors: [] }
+    nodes = graph[:nodes]
+    edges = graph[:edges]
+
+    errors << "actions/ yields no nodes" if nodes.empty?
+    # D16: uniqueness is checked over the node array, not edges.keys - a
+    # Hash key set is unique by construction, so checking edges.keys can
+    # never fire.
+    errors << "duplicate node ids in synthetic chain" if nodes.uniq.length != nodes.length
+
+    # D16: every needs target is checked against the declared node list,
+    # not the node list against its own key set (nodes - edges.keys, which
+    # can never differ since the builder mints edges.keys from nodes).
+    (edges.values.flatten.uniq - nodes).each do |id|
+      errors << "needs target #{id.inspect} names no declared node"
+    end
+
+    cyc = GraphEdges.cycle(edges)
+    errors << "cyclic graph, cannot validate: #{cyc.join(' > ')}" if cyc
+
+    { ok: errors.empty?, missing: [], errors: errors }
+  end
+end

package/scripts/node-packet

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "lib/node_packet"
+require_relative "lib/savepoint"
+
+# node-packet - the CLI over NodePacket (intent 338, G5). Builds one node's
+# whole input from disk and writes it to packets/<node>--a<N>.packet (or
+# --out), printing a parsable summary and the exact node-transition running
+# command intent 340's runner should record.
+#
+# Usage:
+#   node-packet <intent_dir> --node <id> [--budget N] [--hop-tokens N]
+#               [--holder H] [--expires E] [--model M] [--attempt N]
+#               [--out PATH] [--force]
+#
+# Exit codes (spec D17, shared with node-transition's family):
+#   0 - the packet was written (or the identical bytes already existed)
+#   2 - usage: not an intent directory, missing --node, or an unknown node
+#   3 - an unreadable, cyclic or unparsable graph, node file, or record
+#   4 - overflow past the third cut; nothing was written
+#   5 - an existing attempt file whose bytes differ; nothing was written
+module NodePacketCLI
+  module_function
+
+  def usage
+    warn "Usage: node-packet <intent_dir> --node <id> [--budget N] [--hop-tokens N] " \
+         "[--holder H] [--expires E] [--model M] [--attempt N] [--out PATH] [--force]"
+  end
+
+  def intent_directory?(dir)
+    dir && File.directory?(dir) && File.exist?(Savepoint.intent_file(dir))
+  end
+
+  def opt(args, name)
+    (i = args.index(name)) && args[i + 1]
+  end
+
+  def main(argv)
+    args = argv.dup
+    intent_dir_arg = args.shift
+
+    unless intent_directory?(intent_dir_arg && File.expand_path(intent_dir_arg))
+      warn "node-packet: #{intent_dir_arg.inspect} is not an intent directory"
+      usage
+      exit 2
+    end
+    intent_dir = File.expand_path(intent_dir_arg)
+
+    node = opt(args, "--node")
+    if node.to_s.strip.empty?
+      warn "node-packet: --node is required"
+      usage
+      exit 2
+    end
+
+    budget = opt(args, "--budget")
+    hop_tokens = opt(args, "--hop-tokens")
+    attempt = opt(args, "--attempt")
+    out = opt(args, "--out")
+    holder = opt(args, "--holder")
+    expires = opt(args, "--expires")
+    model = opt(args, "--model")
+    force = args.include?("--force")
+
+    result = NodePacket.build(
+      intent_dir: intent_dir,
+      node: node,
+      budget_tokens: budget ? budget.to_i : NodePacket::DEFAULT_BUDGET_TOKENS,
+      hop_tokens: hop_tokens ? hop_tokens.to_i : NodePacket::DEFAULT_HOP_TOKENS,
+      holder: holder,
+      expires: expires,
+      model: model,
+      attempt: attempt ? attempt.to_i : nil,
+      out: out,
+      force: force,
+    )
+
+    if result[:ok]
+      puts NodePacket.summary_line(result)
+      puts result[:running_command]
+      exit 0
+    end
+
+    Array(result[:errors]).each { |e| warn "node-packet: #{e}" }
+    puts result[:needs_decision_command] if result[:needs_decision_command]
+    exit result[:exit_code]
+  end
+end
+
+NodePacketCLI.main(ARGV) if $PROGRAM_NAME == __FILE__