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

package/scripts/intent-screen

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+# intent-screen (intent 316) - prints the intent screen for one intent directory:
+# the title, the field table (Store, Status, Stage, Savepoint, Progress, Next,
+# Insight, each with a note), and the Steps table, filled from the record by
+# scripts/lib/intent_screen.rb. The session adds the What-this-means bullets and
+# the close; it never edits the numbers.
+#
+# Usage:
+#   intent-screen <intent_dir> [--template <path>] [--ansi]
+#
+# The store root is the directory two levels above the intent (<root>/store/<id--slug>);
+# the template defaults to templates/intent-screen.md next to this script's dir,
+# in-repo (<repo>/scripts -> <repo>/templates) and installed (~/.plastic/scripts ->
+# ~/.plastic/templates) alike.
+#
+# --ansi (intent 316a, O3): emits scripts/lib/intent_screen_ansi.rb's styled
+# truecolor block instead of the plain Markdown screen. Plain stays the
+# default with no flag. Two things force plain even WITH --ansi (D18): NO_COLOR
+# present in the environment (any value counts), or a non-TTY stdout — the
+# true default form of D2, not IntentScreenAnsi's own uncoloured layout. The
+# library (scripts/lib/intent_screen_ansi.rb) is pure and never reads either;
+# this script is the one place allowed to.
+#
+# Exit codes:
+#   0 - the screen is on stdout
+#   2 - usage error, or the path is not an intent directory (one line on stderr)
+#
+# Harness-agnostic core: no harness assumption lives here. This script holds
+# the plain/ANSI selection (intent 316a1, D3) and belongs to the same
+# harness-agnostic core as lib/intent_screen.rb and lib/intent_screen_ansi.rb.
+
+require_relative "lib/intent_screen"
+require_relative "lib/intent_screen_ansi"
+
+def usage_abort(message)
+  warn "intent-screen: #{message}"
+  exit 2
+end
+
+args = ARGV.dup
+template_path = nil
+ansi = false
+positional = []
+while (arg = args.shift)
+  case arg
+  when "--template"
+    template_path = args.shift or usage_abort("--template needs a path")
+  when "--ansi"
+    ansi = true
+  else
+    usage_abort("unknown flag #{arg.inspect}") if arg.start_with?("--")
+    positional << arg
+  end
+end
+
+usage_abort("usage: intent-screen <intent_dir> [--template <path>] [--ansi]") unless positional.length == 1
+intent_dir = File.expand_path(positional.first)
+usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
+
+store_root = File.expand_path("../..", intent_dir)
+template_path ||= File.expand_path("../templates/intent-screen.md", __dir__)
+usage_abort("template not found at #{template_path}") unless File.exist?(template_path)
+
+plain = -> { IntentScreen.render(intent_dir: intent_dir, store_root: store_root, template: File.read(template_path)) }
+
+degrade_to_plain = ENV.key?("NO_COLOR") || !$stdout.tty?
+
+$stdout.write(
+  if ansi && !degrade_to_plain
+    IntentScreenAnsi.render(intent_dir: intent_dir, store_root: store_root, color: true)
+  else
+    plain.call
+  end
+)
+exit 0

package/scripts/lib/action_graph_shim.rb

@@ -0,0 +1,277 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "graph_file"
+require_relative "graph_edges"
+require_relative "node_file"
+require_relative "savepoint"
+require_relative "work_graph_validator"
+
+# ActionGraphShim (intent 342, G9): a read-time backward shim that presents
+# any intent directory's actions/*.md as a node graph, in the record shape
+# NodeFile.parse returns, so 336, 338 and 339 read a legacy intent through
+# the same call they already use for an authored graph.md (spec.md D1-D18).
+#
+# Writes nothing, anywhere, ever (D1). An authored graph.md always wins over
+# the synthetic chain (D3) - the reverse of 334's forward shim, which
+# resolves content and prefers the older, richer source. This one resolves
+# structure, where an authored graph is the only real graph.
+module ActionGraphShim
+  module_function
+
+  # D10's heading test: unchanged, four tokens, verified correct on the live
+  # store. Governs only whether a "## Files ..." heading itself is negated
+  # (e.g. "## Files you must NOT change"), never the section body.
+  FILES_NEGATION_RE = /\bnot\b|\bnever\b|\bavoid\b|don't/i.freeze
+
+  # D19's body-truncation vocabulary: the four heading tokens plus the
+  # exclusion phrases the live corpus actually uses ("Out of bounds, owned
+  # by leads running in parallel right now:" matched none of the original
+  # four). Governs whether a body LINE truncates the files harvest -
+  # never the heading test above, which stays on FILES_NEGATION_RE.
+  FILES_EXCLUSION_RE = /\bnot\b|\bnever\b|\bavoid\b|don't|\bout of bounds\b|\bout of scope\b|\bhands off\b|\bleave alone\b|\bexcluded\b/i.freeze
+
+  BACKTICK_RE = /`([^`]+)`/.freeze
+  PROVEN_BY_LABEL_RE = /\AS\d+\z/.freeze
+
+  # :authored when graph.md exists, :actions when it does not but the intent
+  # holds at least one real action file (D7's exact realness test, reused
+  # rather than reimplemented so the shim can never disagree with
+  # Savepoint.has_real_action? about whether an intent has work in it), :none
+  # otherwise. A directory that does not exist returns :none and never
+  # raises.
+  def shape(intent_dir)
+    return :none unless intent_dir && File.directory?(intent_dir.to_s)
+    return :authored if File.exist?(File.join(intent_dir, "graph.md"))
+    return :actions if Savepoint.has_real_files_in?("actions", intent_dir)
+
+    :none
+  end
+
+  # The seven-key hash GraphFile.parse returns (ok:, goal:, decisions:,
+  # graph:, status:, verify:, errors:), for whichever shape the directory
+  # is in. On :authored this is literally GraphFile.parse, unmodified (D3).
+  # On :actions the same hash is built from the action files, with goal:,
+  # decisions: and status: nil (a 2024 action file was never asked for
+  # them) and verify: a fixed reason so a trivial-bar check the caller may
+  # run stays self-consistent. On :none it is GraphFile.parse's own
+  # not-found failure, produced by delegating to it rather than
+  # reformatting the message ourselves.
+  def view(intent_dir)
+    case shape(intent_dir)
+    when :authored
+      GraphFile.parse(File.join(intent_dir, "graph.md"))
+    when :actions
+      synth = synthetic_graph(intent_dir)
+      {
+        ok: synth[:errors].empty?,
+        goal: nil,
+        decisions: nil,
+        graph: synth,
+        status: nil,
+        verify: { reason: "backward shim: legacy actions/ carry no verify node" },
+        errors: synth[:errors],
+      }
+    else
+      # 342 post-execution review, should-fix 5: a nil intent_dir must never
+      # raise. shape(nil) is already nil-guarded, so `view` and `needs`
+      # honor the same contract rather than raising a File.join TypeError.
+      return GraphFile.failure(["graph file not found: #{intent_dir.inspect}"]) unless intent_dir
+
+      GraphFile.parse(File.join(intent_dir, "graph.md"))
+    end
+  end
+
+  # Node records for either shape (D8), always carrying NodeFile.parse's own
+  # key set (ok:, node:, kind:, files:, budget:, body:, errors:) plus
+  # needs:, path: and proven_by:. [] on :none, never a raise on a real
+  # directory.
+  def nodes(intent_dir)
+    case shape(intent_dir)
+    when :authored
+      authored_nodes(intent_dir)
+    when :actions
+      synthetic_nodes(intent_dir)
+    else
+      []
+    end
+  end
+
+  # The needs targets for one node id, under either shape; [] for an id the
+  # graph does not declare, and [] for a directory with no graph at all.
+  def needs(intent_dir, node_id)
+    graph = view(intent_dir)[:graph]
+    return [] unless graph
+
+    (graph[:edges] || {})[node_id] || []
+  end
+
+  # --- authored shape -------------------------------------------------------
+
+  def authored_nodes(intent_dir)
+    parsed = GraphFile.parse(File.join(intent_dir, "graph.md"))
+    edges = parsed.dig(:graph, :edges) || {}
+
+    # 342 post-execution review, nit 8: sort_key numerically over the
+    # basename, the same key the synthetic chain uses, so an authored
+    # intent with ten or more nodes orders n10 after n9 rather than
+    # lexically between n1 and n2.
+    Dir.glob(File.join(intent_dir, "nodes", "*.md"))
+       .sort_by { |path| sort_key(File.basename(path)) }
+       .map do |path|
+      nf = NodeFile.parse(path)
+      nf.merge(
+        needs: edges[nf[:node]] || [],
+        path: path,
+        proven_by: proven_by_labels(nf[:body].to_s)
+      )
+    end
+  end
+
+  # --- actions shape ----------------------------------------------------------
+
+  # {nodes:, edges:, errors:} built directly over the minted chain, in the
+  # same shape GraphEdges.parse returns, rather than rendering a "## Graph"
+  # section and reparsing it.
+  def synthetic_graph(intent_dir)
+    ids = real_action_files(intent_dir).each_index.map { |i| "n#{i + 1}" }
+    edges = {}
+    ids.each_with_index { |id, i| edges[id] = i.zero? ? [] : [ids[i - 1]] }
+    { nodes: ids, edges: edges, errors: [] }
+  end
+
+  def synthetic_nodes(intent_dir)
+    files = real_action_files(intent_dir)
+    files.each_with_index.map do |path, i|
+      id = "n#{i + 1}"
+      needs_targets = i.zero? ? [] : ["n#{i}"]
+      begin
+        text = File.read(path)
+        {
+          ok: true,
+          node: id,
+          kind: "work",
+          files: files_section_paths(text),
+          budget: nil,
+          body: text,
+          errors: [],
+          needs: needs_targets,
+          path: path,
+          proven_by: proven_by_labels(text),
+        }
+      rescue StandardError => e
+        {
+          ok: false,
+          node: id,
+          kind: "work",
+          files: [],
+          budget: nil,
+          body: nil,
+          errors: ["could not read #{path}: #{e.message}"],
+          needs: needs_targets,
+          path: path,
+          proven_by: [],
+        }
+      end
+    end
+  end
+
+  # Real action files (File.file?, non-zero size, Savepoint.stage_file_present?
+  # - D7's own three-part predicate, applied per file since has_real_files_in?
+  # only answers true/false), ordered by the integer trailing the basename,
+  # falling back to the basename itself so the key is a total order over
+  # every basename shape the live store holds (D4).
+  def real_action_files(intent_dir)
+    Dir.glob(File.join(intent_dir.to_s, "actions", "*.md"))
+       .select { |f| File.file?(f) && File.size(f) > 0 && Savepoint.stage_file_present?(f) }
+       .sort_by { |f| sort_key(File.basename(f)) }
+  end
+
+  def sort_key(basename)
+    m = basename.match(/\d+/)
+    m ? [0, m[0].to_i, basename] : [1, 0, basename]
+  end
+
+  # The first heading whose leading token is "Files" (case-insensitively),
+  # unless the heading text carries a negation, in which case it is not a
+  # files section and the search continues (D10). Paths come out of that
+  # section's BODY through extract_files_paths, which is itself
+  # negation-aware and fence-aware (D17, D18). No qualifying heading gives
+  # [] (D9).
+  def files_section_paths(text)
+    NodeFile.split_by_headings(text).each do |heading, section|
+      next unless files_heading?(heading)
+
+      return extract_files_paths(section.to_s)
+    end
+    []
+  end
+
+  # Fence-aware (D18) and negation-aware over the section body, not only
+  # its heading (D17). D10 already stops a heading like "## Files you must
+  # NOT change" from being read as a files section at all; this handles
+  # the equally common case where a legitimate "## Files to touch" heading
+  # is followed, inside the same section, by an out-of-bounds paragraph -
+  # live on this intent's own dogfood fixture. A fenced block is dropped
+  # before anything else runs, reusing NodeFile.each_fence_line rather than
+  # a bare backtick scan, which is exactly what that helper exists to
+  # prevent.
+  #
+  # Lines are scanned in document order; harvesting stops at the first line
+  # an exclusion GOVERNS (D19), not merely mentions - a negation is a false
+  # positive as often as a real exclusion clause, since an action file
+  # routinely annotates an in-bounds path with a "do NOT rename it" aside.
+  # governs_exclusion? draws the line: the match governs when it begins
+  # before the line's first backtick (an exclusion clause introducing
+  # paths) or when the line carries no backtick at all (a bare warning
+  # sentence); it annotates, and the line is kept, when the match falls
+  # after the first backtick (a parenthetical about a path already named).
+  # Any span that still holds a newline is rejected as a backstop: a path
+  # is never more than one line.
+  def extract_files_paths(section)
+    kept = +""
+    NodeFile.each_fence_line(section) do |line, fenced|
+      next if fenced
+      break if governs_exclusion?(line)
+
+      kept << line
+    end
+    kept.scan(BACKTICK_RE).flatten.reject { |s| s.include?("\n") }.uniq
+  end
+
+  # True when a FILES_EXCLUSION_RE match on this line governs the paths on
+  # it rather than merely annotating one (D19).
+  def governs_exclusion?(line)
+    match = line.match(FILES_EXCLUSION_RE)
+    return false unless match
+
+    first_backtick = line.index("`")
+    first_backtick.nil? || match.begin(0) < first_backtick
+  end
+
+  def files_heading?(heading)
+    stripped = heading.to_s.sub(/\A#+\s*/, "")
+    first_token = stripped.split(/\s+/, 2).first.to_s.sub(/[^A-Za-z]+\z/, "")
+    return false unless first_token.casecmp?("Files")
+
+    !heading.to_s.match?(FILES_NEGATION_RE)
+  end
+
+  # The S\d+ tokens of a file's headings, in heading order, taking a
+  # heading only when it owns at least one table data row (D5) - the same
+  # table-owning rule WorkGraphValidator.has_valid_matrix? and ReportScreen
+  # already apply, reused unmodified rather than adapted, so a prose
+  # mention of an S-label never manufactures a Proven-by source (334's
+  # post-execution review defect, in the other direction).
+  def proven_by_labels(text)
+    labels = []
+    NodeFile.split_by_headings(text).each do |heading, section|
+      next unless NodeFile.table_rows(section).any?
+
+      WorkGraphValidator.heading_tokens(heading).each do |token|
+        labels << token if token.match?(PROVEN_BY_LABEL_RE)
+      end
+    end
+    labels
+  end
+end

package/scripts/lib/arm.rb

@@ -94,8 +94,21 @@ module Arm
     }
   end
 
+  # Owner rule 2026-08-31: does this session already have a live top-level
+  # pointer pointing SOMEWHERE ELSE (the day ledger or another intent)? A
+  # pointer already on this intent is the owner re-arming mid-delivery and
+  # stays idempotent. True means a
+  # conversation session. Reads only; rescues to false (fail open).
+  def preexisting_pointer?(session, home:)
+    path = pointer_path(session, home: home)
+    File.exist?(path) && !File.read(path).to_s.strip.empty?
+  rescue StandardError
+    false
+  end
+
   # --- the pointer -------------------------------------------------------------
 
+
   def pointer_path(session, home:)
     store = global_store(home)
     SessionLedger.pointer_path(store, SessionLedger.short_session_id(nil, session))
@@ -125,12 +138,24 @@ module Arm
   # lock data read and touches nothing.
   def arm(intent_dir:, session:, mode: "auto", home: Dir.home, harness: nil,
           agent: nil, model: nil, thread: nil, now: Time.now, runner: Worktree::ShellRunner.new,
-          host: Socket.gethostname)
+          host: Socket.gethostname, allow_inline: false)
     raise ArgumentError, "mode must be auto or guided" unless %w[auto guided].include?(mode.to_s)
     dir = File.expand_path(intent_dir)
     key = resolve_session(session, store: store_for(dir), intent_id: intent_id_for(dir))
     h = home_for(dir, home: home)
 
+    # Owner rule 2026-08-31: the main session never delivers an intent inline.
+    # A session that already carries a top-level session pointer is a
+    # conversation session (SessionStart wrote it at boot); arming there is
+    # inline delivery and is refused BEFORE any lock is taken. A dispatched or
+    # headless session has no pre-existing pointer and arms freely.
+    # --allow-inline is the explicit owner override. Fail open on read errors:
+    # a broken pointer file must never block a legitimate delivery.
+    if !allow_inline && preexisting_pointer?(key, home: h) &&
+       read_pointer(key, home: h).to_s.strip != intent_id_for(dir)
+      return { status: :inline_refused, lock: nil, worktree: nil, session: key, pointer: nil }
+    end
+
     status, lock = Lock.acquire(dir, session: key, host: host, now: now,
                                 harness: harness, agent: agent, model: model,
                                 thread: thread, run_mode: mode.to_s)

package/scripts/lib/atomic_write.rb

@@ -0,0 +1,31 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# AtomicWrite (intent 334, n2, D19r): a sibling-temp-plus-rename write, the
+# same shape as Lock#write (scripts/lib/lock.rb) - a content write is never
+# an in-place truncate, so a crash mid-write can never leave an empty or
+# half-written target on disk. The temp file is a SIBLING in the same
+# directory as the target, never a system tmpdir, because File.rename can
+# raise EXDEV when the temp and the target live on different filesystems.
+# The temp name ends in .lock (post-execution review, non-blocking 5), the
+# same property Lock#write_temp_path documents: an orphan left by a crash
+# between the write and the rename is covered by the store's existing
+# *.lock gitignore rule rather than swept into its git add -A auto-commit.
+#
+# The renamer is injectable so the interrupted-write case (a rename that
+# raises) is testable with dependency injection, never eval or a global
+# (D19r).
+module AtomicWrite
+  module_function
+
+  def write(path, content, renamer: File.method(:rename))
+    dir = File.dirname(path)
+    temp = File.join(dir, ".#{File.basename(path)}.tmp.#{Process.pid}.#{Time.now.to_f}.#{rand(0xFFFFFF)}.lock")
+    File.write(temp, content)
+    renamer.call(temp, path)
+    true
+  rescue StandardError
+    File.delete(temp) if temp && File.exist?(temp)
+    raise
+  end
+end

package/scripts/lib/core_integrity.rb

@@ -0,0 +1,71 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+
+# CoreIntegrity (intent 340, G7, n1): re-hashes the files an installed
+# ~/.plastic/manifest.json lists, so the runner's own "am I running trusted
+# code" check has one implementation. scripts/doctor.rb's
+# Doctor#check_install_integrity does this same arithmetic inline today,
+# per-agent (Codex/Hermes/Claude), against each agent's own manifest; this
+# module is not a refactor of that (out of scope for this node), it exists
+# so the runner - and a later node that points doctor at it - never have to
+# reimplement the same hashing loop a third time.
+#
+# Pure and side-effect-free: `check` takes plastic_home: and never raises
+# across its boundary. A missing, unreadable, or non-JSON manifest.json is a
+# named refusal (`reason:`), never an exception. A manifest-listed file that
+# no longer exists is reported under `missing`, distinct from `drifted` (a
+# file that exists but no longer hashes to the manifest's recorded value).
+module CoreIntegrity
+  module_function
+
+  def check(plastic_home:)
+    manifest_path = File.join(plastic_home.to_s, "manifest.json")
+    return refusal("manifest.json not found at #{manifest_path}") unless File.exist?(manifest_path)
+
+    raw = begin
+      File.read(manifest_path)
+    rescue StandardError => e
+      return refusal("manifest.json is unreadable: #{e.message}")
+    end
+
+    data = begin
+      JSON.parse(raw)
+    rescue JSON::ParserError => e
+      return refusal("manifest.json is not valid JSON: #{e.message}")
+    end
+
+    files = data.is_a?(Hash) ? data["files"] : nil
+    return refusal("manifest.json's files: is not a mapping") unless files.is_a?(Hash)
+
+    drifted = []
+    missing = []
+    files.each do |path, expected_hash|
+      unless File.exist?(path)
+        missing << path
+        next
+      end
+
+      # v1 minor 6/row 11.16: a tracked file that exists but cannot be read
+      # (permissions changed under this process) must never raise out of a
+      # module whose whole contract is "never raises across its boundary" -
+      # unreadable is reported the same way a hash mismatch is: this
+      # process cannot confirm the file matches what the manifest expects,
+      # which is exactly what `drifted` already means.
+      actual_hash = begin
+        Digest::SHA256.file(path).hexdigest
+      rescue SystemCallError
+        nil
+      end
+      drifted << path if actual_hash.nil? || actual_hash != expected_hash
+    end
+
+    { ok: drifted.empty? && missing.empty?, drifted: drifted, missing: missing, reason: nil }
+  end
+
+  def refusal(reason)
+    { ok: false, drifted: [], missing: [], reason: reason }
+  end
+end

package/scripts/lib/dashboard_screen.rb

@@ -0,0 +1,40 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "report_screen"
+
+# DashboardScreen (intent 331d) - the presentation half of the dashboard
+# screen. scripts/dashboard.rb's screen_fields sources every fact (Active, In
+# delivery, Delivered, Roadmap, Sessions, Changed, the two capped row lists)
+# through the same helpers report-screen and DaySummary already use, turning
+# a missing source into "not recorded" or "none" before it ever reaches
+# here; this module carries no data-sourcing logic of its own, only layout,
+# exactly like ReportScreen.render_state and IntentScreen.render do for
+# their own screens.
+module DashboardScreen
+  module_function
+
+  TEMPLATE_PATH = File.expand_path("../../templates/dashboard-screen.md", __dir__)
+
+  def render(fields, template: nil)
+    out = (template || File.read(TEMPLATE_PATH)).dup
+    out = out.gsub("{{scope}}", fields.fetch(:scope).to_s)
+    out = out.gsub("{{active}}", fields.fetch(:active).to_s)
+    out = out.gsub("{{in_delivery}}", fields.fetch(:in_delivery).to_s)
+    out = out.gsub("{{delivered}}", fields.fetch(:delivered).to_s)
+    out = out.gsub("{{roadmap}}", fields.fetch(:roadmap).to_s)
+    out = out.gsub("{{sessions}}", fields.fetch(:sessions).to_s)
+    out = out.gsub("{{changed}}", fields.fetch(:changed).to_s)
+    out = out.gsub("{{where_we_are.rows}}", where_we_are_rows(fields.fetch(:where_we_are, [])))
+    out = out.gsub("{{where_we_go_next.rows}}", where_we_go_next_rows(fields.fetch(:where_we_go_next, [])))
+    ReportScreen.fit_screen(out.gsub(/\n{3,}/, "\n\n"))
+  end
+
+  def where_we_are_rows(rows)
+    rows.map { |r| "| #{r[:graph_id]} | #{r[:intent]} | #{r[:stage]} | #{r[:progress]} | #{r[:lead]} |" }.join("\n")
+  end
+
+  def where_we_go_next_rows(rows)
+    rows.map { |r| "| #{r[:rank]} | #{r[:graph_id]} | #{r[:intent]} | #{r[:reason]} |" }.join("\n")
+  end
+end

package/scripts/lib/day_summary.rb

@@ -12,6 +12,7 @@ require "time"
 require_relative "session_ledger"
 require_relative "handoff"
 require_relative "lock"
+require_relative "report_screen"
 
 module DaySummary
   module_function
@@ -113,8 +114,12 @@ module DaySummary
         dir = File.join(store_dir, dirname)
         next unless File.directory?(dir) && Lock.fresh?(dir, now: now)
         # A guided session's lock is live but not autonomous; a lock with no
-        # run_mode (a 1.14 auto team) counts as auto.
-        next if (Lock.read(dir) || {})["run_mode"].to_s == "guided"
+        # run_mode (a 1.14 auto team) counts as auto. 317a (B9): when the lock
+        # carries no run_mode, the outcome frontmatter stamp (D5) is asked
+        # before defaulting, so a guided close never reads as auto.
+        run_mode = (Lock.read(dir) || {})["run_mode"].to_s
+        run_mode = ReportScreen.outcome_frontmatter(dir)["mode"].to_s if run_mode.empty?
+        next if run_mode == "guided"
 
         id, slug = dirname.split("--", 2)
         "- #{id} #{slug}: #{last_savepoint_line(dir)}"