@zalom/plastic 2.0.0-alpha.9 → 2.0.1

package/scripts/lib/exec_worktree.rb

@@ -2,7 +2,6 @@
 # frozen_string_literal: true
 
 require "open3"
-require_relative "bridge"
 require_relative "arm"
 require_relative "lock"
 require_relative "worktree"
@@ -29,8 +28,8 @@ require_relative "scaffold_intent"
 # fail-open, see the merge-verification note below), `finisher:` (defaults to
 # `Worktree.method(:finish)`), `status_checker:` (defaults to a `git status --porcelain`
 # lambda). Every seam exists so
-# tests run with no real git, no real worktree removal, and no real bridge file outside a
-# tmpdir.
+# tests run with no real git, no real worktree removal, and no real delivery-lock file
+# outside a tmpdir.
 #
 # MERGE VERIFICATION (delivered disposition only). `Worktree.merge_branch` is deliberately
 # fail-open: on a conflict it runs `git merge --abort`, warns, and returns false, and
@@ -39,7 +38,7 @@ require_relative "scaffold_intent"
 # module never trusts the discarded return value; it asks git directly, AFTER finish, whether
 # the intent's code branch is now an ancestor of the repo's current HEAD
 # (`merged_into_current_branch?` below). `repo` and `branch` are captured BEFORE the finisher
-# runs, because finish deletes the bridge's `worktree` block.
+# runs, because finish deletes the delivery's `worktree` block.
 #
 # DOES NOT RUN A TEST SUITE, in any form. `verify-intent` owns test execution; one concern
 # per script (spec D8).
@@ -60,6 +59,10 @@ module ExecWorktree
   # [stdout, stderr, status] triple Open3.capture3 returns (status responds to
   # success?). A raised error (git missing, corrupt repo) is caught and reported as a
   # nil status, so the caller can fail closed the same way a failed exit status would.
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+
   def default_status_checker
     lambda do |worktree_code|
       Open3.capture3("git", "-C", worktree_code, "status", "--porcelain")
@@ -85,7 +88,7 @@ module ExecWorktree
   # `<repo>/.claude/worktrees/<name>` (scripts/lib/worktree.rb:75), so walking up three
   # directories recovers `<repo>` deterministically, with no I/O and no git.
   def repo_from_worktree_code(worktree_code)
-    return nil if Bridge.blank?(worktree_code)
+    return nil if blank?(worktree_code)
     File.dirname(File.dirname(File.dirname(worktree_code.to_s)))
   end
 
@@ -94,7 +97,7 @@ module ExecWorktree
   # i.e. the merge actually landed. Fails CLOSED (not merged) on a blank repo/branch or a
   # raising runner, so an inconclusive check is never reported as a success.
   def merged_into_current_branch?(runner, repo:, branch:)
-    return false if Bridge.blank?(repo) || Bridge.blank?(branch)
+    return false if blank?(repo) || blank?(branch)
     runner.run("-C", repo, "merge-base", "--is-ancestor", branch, "HEAD").success?
   rescue StandardError
     false
@@ -106,12 +109,12 @@ module ExecWorktree
   # The lock-owner fallback is correct here: this is a teardown step on an intent this
   # session has been delivering.
   def resolve_session(explicit, env_session, intent_dir)
-    return explicit.to_s.strip unless Bridge.blank?(explicit)
-    return env_session.to_s.strip unless Bridge.blank?(env_session)
+    return explicit.to_s.strip unless blank?(explicit)
+    return env_session.to_s.strip unless blank?(env_session)
     lock = Lock.read(intent_dir)
     return nil unless lock
     owner = lock["owner_session"].to_s
-    Bridge.blank?(owner) ? nil : owner
+    blank?(owner) ? nil : owner
   end
 
   # --- result builders (the exit_code/stdout/stderr shape the thin CLIs share) --------
@@ -181,7 +184,7 @@ module ExecWorktree
     merge_line =
       if disposition != "delivered"
         "not attempted (abandoned)"
-      elsif Bridge.blank?(target_branch)
+      elsif blank?(target_branch)
         "merged (integration target branch could not be resolved)"
       else
         "merged into #{target_branch}"
@@ -202,10 +205,10 @@ module ExecWorktree
           runner: Worktree::ShellRunner.new,
           finisher: Worktree.method(:finish),
           status_checker: default_status_checker)
-    return usage_result("--store is required") if Bridge.blank?(store)
-    return usage_result("--id is required") if Bridge.blank?(id)
-    return usage_result("--home is required") if Bridge.blank?(home)
-    return usage_result("--disposition is required") if Bridge.blank?(disposition)
+    return usage_result("--store is required") if blank?(store)
+    return usage_result("--id is required") if blank?(id)
+    return usage_result("--home is required") if blank?(home)
+    return usage_result("--disposition is required") if blank?(disposition)
     unless DISPOSITIONS.include?(disposition)
       return usage_result("--disposition must be one of #{DISPOSITIONS.join('|')} (got #{disposition.inspect})")
     end
@@ -220,16 +223,16 @@ module ExecWorktree
 
     # Step 0: session resolution + pre-flight refusal (D3-mirroring; see resolve_session).
     key_session = resolve_session(session, env_session, intent_dir)
-    if Bridge.blank?(key_session) && File.exist?(Lock.path(intent_dir))
+    if blank?(key_session) && File.exist?(Lock.path(intent_dir))
       return deny_result(EXIT_UNRESOLVED, no_session_message(intent_dir))
     end
 
-    bridge_data = Arm.bridge_hash(intent_dir: intent_dir, home: normalized_home)
-    worktree_code = bridge_data.dig("worktree", "code")
-    return ok_result(nothing_provisioned_message(intent_dir)) if Bridge.blank?(worktree_code)
+    delivery = Arm.delivery(intent_dir: intent_dir, home: normalized_home)
+    worktree_code = delivery.dig("worktree", "code")
+    return ok_result(nothing_provisioned_message(intent_dir)) if blank?(worktree_code)
 
-    branch = bridge_data.dig("worktree", "code_branch")
-    # Captured now, before `finisher.call` below (Worktree.finish) deletes the bridge's
+    branch = delivery.dig("worktree", "code_branch")
+    # Captured now, before `finisher.call` below (Worktree.finish) deletes the delivery's
     # `worktree` block, so the post-finish merge verification (BLOCKING 1/2) still has
     # both `repo` and `branch` to work with.
     repo = repo_from_worktree_code(worktree_code)
@@ -254,7 +257,7 @@ module ExecWorktree
     # disposition only, whether the worktree directory still exists on disk (teardown
     # incomplete); second, for a delivered disposition only, whether the branch actually
     # merged (BLOCKING 1/2, see merged_into_current_branch? above).
-    finisher.call(bridge_data, home: normalized_home, runner: runner,
+    finisher.call(delivery, home: normalized_home, runner: runner,
                   merge: disposition == "delivered")
 
     removed = !Dir.exist?(worktree_code)

package/scripts/lib/feedback_report.rb

@@ -18,7 +18,7 @@ require "fileutils"
 # Trust model: this class never sends anything anywhere. `compose` returns a
 # Result carrying a local file path and a browser URL; only the human, in
 # their own authenticated browser, submits it. There is no send method here
-# and there must never be one (see skills/feedback/references/transport-and-privacy.md).
+# and there must never be one (see SECURITY.md).
 class FeedbackReport
   GITHUB_REPO = "zalom/plastic"
   CAP_BYTES = 7500

package/scripts/lib/graph_edges.rb

@@ -0,0 +1,137 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# 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, 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, review A6).
+#
+# Grammar (D2r/D3r): a list item shaped "- <id> needs <target> [<target>
+# ...]", ending at end of line. The single literal target "nothing" declares
+# a root and must be the ONLY target on the line. Any line that does not
+# start with "- <token> needs" is prose and is skipped in silence. A line
+# that DOES look like an edge is held to the grammar strictly: no target at
+# 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 (review A7).
+#
+# Pure and side-effect-free; never raises across the boundary, matching the
+# Result-hash convention every library in scripts/lib/ follows.
+module GraphEdges
+  module_function
+
+  EDGE_LEAD_RE = /\A-\s*(\S+)\s+needs\b(.*)\z/.freeze
+  TOKEN_RE = /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/.freeze
+  ROOT_TARGET = "nothing"
+
+  # {nodes:, edges:, errors:} - nodes is the declared ids together with every
+  # 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)
+    declared_order = []
+    edges = {}
+    targeted = []
+    errors = []
+
+    section_text.to_s.each_line do |raw_line|
+      line = raw_line.chomp("\n").chomp("\r")
+      stripped = line.strip
+      next if stripped.empty?
+
+      m = stripped.match(EDGE_LEAD_RE)
+      next unless m
+
+      id = m[1]
+      raw_targets = m[2].to_s.strip.split(/\s+/)
+
+      if raw_targets.empty?
+        errors << "malformed edge line, no target: #{stripped.inspect}"
+        next
+      end
+
+      if raw_targets.include?(ROOT_TARGET) && raw_targets.length > 1
+        errors << "root target #{ROOT_TARGET.inspect} mixed with a real target, root must be the only target: #{stripped.inspect}"
+        next
+      end
+
+      bad_token = raw_targets.find { |t| t != ROOT_TARGET && !t.match?(TOKEN_RE) }
+      if bad_token
+        errors << "prose tail after targets: #{stripped.inspect}"
+        next
+      end
+
+      if edges.key?(id)
+        errors << "duplicate node declaration for #{id.inspect}: #{stripped.inspect}"
+        next
+      end
+
+      targets = raw_targets == [ROOT_TARGET] ? [] : raw_targets
+      declared_order << id
+      edges[id] = targets
+      targeted.concat(targets)
+    end
+
+    nodes = declared_order.dup
+    targeted.each { |t| nodes << t unless nodes.include?(t) }
+
+    { nodes: nodes, edges: edges, errors: errors }
+  end
+
+  # The cycle as a path with the entry id repeated (D4r), or nil when the
+  # graph is acyclic. A node reachable by two distinct paths (a diamond) is
+  # never mistaken for a cycle: once a node's whole subtree is walked clean
+  # it is marked visited and never re-examined.
+  def cycle(edges)
+    visiting = {}
+    visited = {}
+    path = []
+
+    edges.each_key do |node|
+      next if visited[node]
+      found = walk(node, edges, visiting, visited, path)
+      return found if found
+    end
+    nil
+  end
+
+  def walk(node, edges, visiting, visited, path)
+    if visiting[node]
+      idx = path.index(node)
+      return path[idx..] + [node]
+    end
+    return nil if visited[node]
+
+    visiting[node] = true
+    path.push(node)
+    (edges[node] || []).each do |target|
+      found = walk(target, edges, visiting, visited, path)
+      return found if found
+    end
+    path.pop
+    visiting.delete(node)
+    visited[node] = true
+    nil
+  end
+
+  # The declared work ids whose `needs` reach a verify node without passing
+  # through another verify node (343 D7), in declaration order. `kinds` maps
+  # an id to its node kind, so this module stays blind to where a kind lives.
+  def review_fixes(edges, kinds)
+    edges.keys.select { |id| kinds[id] == "work" && reaches_verify?(id, edges, kinds, {}) }
+  end
+
+  def reaches_verify?(node, edges, kinds, seen)
+    (edges[node] || []).any? do |target|
+      next false if seen[target]
+
+      seen[target] = true
+      kinds[target] == "verify" || reaches_verify?(target, edges, kinds, seen)
+    end
+  end
+end

package/scripts/lib/graph_file.rb

@@ -0,0 +1,246 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "graph_edges"
+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 (review D19r). Fence-aware everywhere a
+# heading is located, so a fenced example carrying a fake "## " line never
+# splits or ends a real section (review A8's sibling concern, applied to
+# section boundaries rather than edge lines).
+module GraphFile
+  module_function
+
+  FENCE_LINE_RE = /\A\s{0,3}(`{3,}|~{3,})/.freeze
+  DIRECTIVE_RE = /\A-\s*verify:\s*none(?:\s+reason=(.*))?\z/i.freeze
+
+  # {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 (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)
+
+    content = File.read(path)
+    goal = section_body(content, "## Goal")
+    decisions = section_body(content, "## Decisions")
+    graph_section = section_body(content, "## Graph")
+    status = section_body(content, "## Status")
+
+    errors = []
+    if graph_section.nil?
+      errors << "missing ## Graph section"
+      return { ok: false, goal: goal, decisions: decisions, graph: nil, status: status, verify: nil, errors: errors }
+    end
+
+    directive, directive_errors, remaining = extract_verify_directive(graph_section)
+    errors.concat(directive_errors)
+
+    parsed_graph = GraphEdges.parse(strip_fenced_blocks(remaining))
+    errors.concat(parsed_graph[:errors])
+    errors << "## Graph declares no nodes" if parsed_graph[:nodes].empty?
+
+    { ok: errors.empty?, goal: goal, decisions: decisions, graph: parsed_graph, status: status, verify: directive, errors: errors }
+  end
+
+  def failure(errors)
+    { ok: false, goal: nil, decisions: nil, graph: nil, status: nil, verify: nil, errors: errors }
+  end
+
+  # Rows shaped {node:, state:, detail:} parsed back from the ## Status
+  # table (D8r's round-trip guarantee).
+  def status_rows(path)
+    parsed = parse(path)
+    rows_from_table(parsed[:status])
+  end
+
+  # Replace the whole ## Status section with rows, creating the section if
+  # absent. Refuses a cyclic graph (D8r); goes through AtomicWrite (D19r).
+  def write_status(path, rows, renamer: File.method(:rename))
+    guard = refuse_if_cyclic(path)
+    return guard if guard
+
+    content = File.read(path)
+    new_content = replace_or_append_section(content, "## Status", render_status_table(rows))
+    AtomicWrite.write(path, new_content, renamer: renamer)
+    { ok: true, errors: [] }
+  end
+
+  # Append one answered decision as a list item to ## Decisions (C26),
+  # leaving every other section byte-identical. Refuses a cyclic graph.
+  def append_decision(path, text, renamer: File.method(:rename))
+    guard = refuse_if_cyclic(path)
+    return guard if guard
+
+    content = File.read(path)
+    bounds = section_bounds(content, "## Decisions")
+    return { ok: false, errors: ["missing ## Decisions section"] } unless bounds
+
+    start_idx, end_idx = bounds
+    heading_line_end = line_end(content, start_idx)
+    body = content[heading_line_end...end_idx]
+    trimmed = body.rstrip
+    trailing = body[trimmed.length..]
+    new_body = trimmed.empty? ? "- #{text}#{trailing}" : "#{trimmed}\n- #{text}#{trailing}"
+    new_content = content[0...heading_line_end] + new_body + content[end_idx..]
+    AtomicWrite.write(path, new_content, renamer: renamer)
+    { ok: true, errors: [] }
+  end
+
+  def refuse_if_cyclic(path)
+    parsed = parse(path)
+    return { ok: false, errors: parsed[:errors] } if parsed[:graph].nil?
+
+    cyc = GraphEdges.cycle(parsed[:graph][:edges])
+    return { ok: false, errors: ["cyclic graph, refusing to write: #{cyc.join(' > ')}"] } if cyc
+
+    nil
+  end
+
+  # --- verify: none directive --------------------------------------------------
+
+  def extract_verify_directive(graph_section)
+    return [nil, [], graph_section] if graph_section.nil?
+
+    reason = nil
+    present = false
+    errors = []
+    remaining_lines = []
+
+    graph_section.each_line do |line|
+      stripped = line.strip
+      m = stripped.match(DIRECTIVE_RE)
+      if m
+        present = true
+        captured = m[1].to_s.strip
+        if captured.empty?
+          errors << "verify: none requires reason=<text>: #{stripped.inspect}"
+        else
+          reason = captured
+        end
+      else
+        remaining_lines << line
+      end
+    end
+
+    directive = present ? { reason: reason } : nil
+    [directive, errors, remaining_lines.join]
+  end
+
+  # D18: drop every fenced line from `text`, so a fenced example edge inside a
+  # hand-written graph.md or roadmap ## Graph section is never handed to
+  # GraphEdges as real edge text. Non-fenced lines pass through unchanged.
+  def strip_fenced_blocks(text)
+    lines = []
+    each_fence_line(text) { |line, fenced| lines << line unless fenced }
+    lines.join
+  end
+
+  # --- fence-aware section location ---------------------------------------------
+
+  def each_fence_line(text)
+    return enum_for(:each_fence_line, text) unless block_given?
+
+    marker = nil
+    text.to_s.each_line do |line|
+      if marker
+        yield line, true
+        m = line.match(FENCE_LINE_RE)
+        next unless m && m[1][0] == marker[0] && m[1].length >= marker[1]
+        next unless line.sub(FENCE_LINE_RE, "").strip.empty?
+
+        marker = nil
+      else
+        m = line.match(FENCE_LINE_RE)
+        if m
+          marker = [m[1][0], m[1].length]
+          yield line, true
+        else
+          yield line, false
+        end
+      end
+    end
+  end
+
+  # [start_of_heading_line, start_of_next_top_level_heading_or_EOF] byte
+  # offsets for the FIRST line, outside any fence, whose stripped text
+  # exactly equals heading_text. nil when no such line exists.
+  def section_bounds(content, heading_text)
+    offset = 0
+    heading_start = nil
+
+    each_fence_line(content) do |line, fenced|
+      if !fenced && heading_start.nil? && line.strip == heading_text
+        heading_start = offset
+      elsif !fenced && heading_start && offset > heading_start && line.match?(/\A##[^#]/)
+        return [heading_start, offset]
+      end
+      offset += line.length
+    end
+
+    heading_start ? [heading_start, offset] : nil
+  end
+
+  def section_body(content, heading_text)
+    bounds = section_bounds(content, heading_text)
+    return nil unless bounds
+
+    start_idx, end_idx = bounds
+    content[(line_end(content, start_idx))...end_idx].to_s
+  end
+
+  def line_end(content, start_idx)
+    idx = content.index("\n", start_idx)
+    idx ? idx + 1 : content.length
+  end
+
+  def replace_or_append_section(content, heading_text, body_text)
+    rendered_body = body_text.to_s
+    rendered_body += "\n" unless rendered_body.end_with?("\n")
+    section = "#{heading_text}\n#{rendered_body}"
+
+    bounds = section_bounds(content, heading_text)
+    if bounds
+      start_idx, end_idx = bounds
+      tail = content[end_idx..].to_s
+      section += "\n" unless tail.empty?
+      content[0...start_idx] + section + tail
+    else
+      head = content.dup
+      head += "\n" unless head.end_with?("\n")
+      head += "\n" unless head.end_with?("\n\n")
+      head + section
+    end
+  end
+
+  # --- table rendering and reading -----------------------------------------------
+
+  def render_status_table(rows)
+    lines = ["| Node | State | Detail |", "| --- | --- | --- |"]
+    rows.each { |r| lines << "| #{r[:node]} | #{r[:state]} | #{r[:detail]} |" }
+    "#{lines.join("\n")}\n"
+  end
+
+  def rows_from_table(text)
+    return [] if text.nil?
+
+    lines = []
+    each_fence_line(text) do |line, fenced|
+      next if fenced
+
+      stripped = line.strip
+      lines << stripped if stripped.start_with?("|")
+    end
+    sep_idx = lines.index { |l| l.match?(/\A\|[\s:|-]+\|?\z/) }
+    return [] unless sep_idx
+
+    lines[(sep_idx + 1)..].map do |l|
+      cells = l.split("|", -1).map(&:strip)[1..-2].to_a
+      { node: cells[0], state: cells[1], detail: cells[2] }
+    end
+  end
+end