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

package/scripts/lib/installer_core.rb

@@ -76,8 +76,25 @@ class InstallerCore
     @agents = agents
   end
 
+  # Reads the package version from `package.json` when present (the source
+  # tree, and any dev checkout), falling back to the bare `VERSION` file the
+  # installer copies to `~/.plastic` (row B, spec 315b): an installed system
+  # carries VERSION but never package.json, so `rollback.rb` and `update.rb`
+  # constructing an InstallerCore with `package_root: ~/.plastic` crashed with
+  # a raw Errno::ENOENT before this fallback existed. Raises a named error,
+  # not a bare ENOENT, when neither file exists, so the caller is not
+  # misdirected toward the wrong missing file.
   def read_package_version(root)
-    File.read(File.join(root, "package.json")).then { |s| JSON.parse(s)["version"] }
+    package_json = File.join(root, "package.json")
+    version_file = File.join(root, "VERSION")
+
+    if File.exist?(package_json)
+      JSON.parse(File.read(package_json))["version"]
+    elsif File.exist?(version_file)
+      File.read(version_file).strip
+    else
+      raise "cannot determine the package version: neither #{package_json} nor #{version_file} exists"
+    end
   end
 
   # --- Channel derivation (the channel is encoded in the version string) ---
@@ -314,12 +331,26 @@ class InstallerCore
     end
   end
 
+  # Intent 331a (D6/R7): a screen kind file (scripts/lib/screens/<kind>.rb)
+  # must reach an installed ~/.plastic the same way a new template or hook
+  # does - glob-derived, so "add a file, not a diff" is actually true for an
+  # installed Plastic, not just an in-repo one. This repo ships none yet;
+  # the glob answers {} until one exists.
+  def screen_files
+    Dir.glob(File.join(package_root, "scripts", "lib", "screens", "*.rb")).each_with_object({}) do |path, acc|
+      next unless File.file?(path)
+
+      rel = File.join("scripts", "lib", "screens", File.basename(path))
+      acc[rel] = rel
+    end
+  end
+
   # Files copied into ~/.plastic on install/update. Every verb script + the shared lib
   # must be here so the installed ~/.plastic/scripts copy is self-complete (sync-guarded
-  # by install_sync_test). The templates half is glob-derived (template_files above); the
-  # rest stays a hand-written literal.
+  # by install_sync_test). The templates and screen-kind halves are glob-derived
+  # (template_files, screen_files above); the rest stays a hand-written literal.
   def core_files
-    hand_registered_files.merge(template_files).merge(hook_files)
+    hand_registered_files.merge(template_files).merge(hook_files).merge(screen_files)
   end
 
   def hand_registered_files
@@ -342,6 +373,9 @@ class InstallerCore
       "scripts/lib/release_guard.rb" => "scripts/lib/release_guard.rb",
       "scripts/lib/bridge.rb" => "scripts/lib/bridge.rb",
       "scripts/lib/savepoint.rb" => "scripts/lib/savepoint.rb",
+      "scripts/lib/guarded_append.rb" => "scripts/lib/guarded_append.rb",
+      "scripts/lib/node_ledger.rb" => "scripts/lib/node_ledger.rb",
+      "scripts/node-transition" => "scripts/node-transition",
       "scripts/lib/arm.rb" => "scripts/lib/arm.rb",
       "scripts/lib/lock.rb" => "scripts/lib/lock.rb",
       "scripts/plastic-lock" => "scripts/plastic-lock",
@@ -383,6 +417,9 @@ class InstallerCore
       "scripts/lib/harness_text.rb" => "scripts/lib/harness_text.rb",
       "scripts/codex-hook" => "scripts/codex-hook",
       "scripts/spawn-preamble" => "scripts/spawn-preamble",
+      "scripts/lib/report_screen.rb" => "scripts/lib/report_screen.rb",
+      "scripts/report-screen" => "scripts/report-screen",
+      "scripts/savepoint-note" => "scripts/savepoint-note",
       "scripts/lib/store_provisioning.rb" => "scripts/lib/store_provisioning.rb",
       "scripts/provision-project-store" => "scripts/provision-project-store",
       "scripts/lib/project_validator.rb" => "scripts/lib/project_validator.rb",
@@ -403,6 +440,7 @@ class InstallerCore
       "scripts/exec-worktree" => "scripts/exec-worktree",
       "scripts/doctor.rb" => "scripts/doctor.rb",
       "scripts/lib/doctor_core.rb" => "scripts/lib/doctor_core.rb",
+      "scripts/lib/hook_replay.rb" => "scripts/lib/hook_replay.rb",
       "scripts/lib/rule_catalog.rb" => "scripts/lib/rule_catalog.rb",
       "scripts/lib/doctor_exclusions.rb" => "scripts/lib/doctor_exclusions.rb",
       "scripts/lib/doctor_session_ledger.rb" => "scripts/lib/doctor_session_ledger.rb",
@@ -423,7 +461,96 @@ class InstallerCore
       "scripts/lib/day_summary.rb" => "scripts/lib/day_summary.rb",
       "scripts/write-handoff" => "scripts/write-handoff",
       "scripts/day-summary" => "scripts/day-summary",
+      "scripts/lib/intent_screen.rb" => "scripts/lib/intent_screen.rb",
+      "scripts/intent-screen" => "scripts/intent-screen",
       "scripts/hook-savepoint" => "scripts/hook-savepoint",
+      # Intent 316a: hooks/* only glob-copies scripts/*, never scripts/lib/*
+      # (see hook_files above), so the two lib files a require_relative
+      # between themselves are unguarded there — these three literal
+      # entries are their only protection (test/install_sync_test.rb:23-29
+      # greps installer_core.rb's own source text for "scripts/<name>").
+      "scripts/lib/intent_screen_ansi.rb" => "scripts/lib/intent_screen_ansi.rb",
+      "scripts/lib/screen_paint.rb" => "scripts/lib/screen_paint.rb",
+      "scripts/lib/message_display.rb" => "scripts/lib/message_display.rb",
+      # Intent 331d (A1): scripts/dashboard.rb require_relatives this lib
+      # directly; templates/dashboard-screen.md and scripts/lib/screens/
+      # dashboard.rb are glob-derived (template_files, screen_files above)
+      # and need no entry here.
+      "scripts/lib/dashboard_screen.rb" => "scripts/lib/dashboard_screen.rb",
+      "scripts/hook-message-display" => "scripts/hook-message-display",
+      # Intent 334 (G1): the node file and graph.md library, plus its
+      # validator and CLI (327 D40/D41).
+      "scripts/lib/graph_edges.rb" => "scripts/lib/graph_edges.rb",
+      "scripts/lib/node_file.rb" => "scripts/lib/node_file.rb",
+      "scripts/lib/atomic_write.rb" => "scripts/lib/atomic_write.rb",
+      "scripts/lib/graph_file.rb" => "scripts/lib/graph_file.rb",
+      "scripts/lib/work_graph_validator.rb" => "scripts/lib/work_graph_validator.rb",
+      "scripts/validate-work-graph" => "scripts/validate-work-graph",
+      # Intent 335a: every id an intent has ever seen, so a deleted node's id
+      # is never reissued to a new node with the dead one's ledger history.
+      "scripts/lib/node_ids.rb" => "scripts/lib/node_ids.rb",
+      # Intent 339 (G6): the generated outcome.md library and its CLI.
+      "scripts/lib/outcome_report.rb" => "scripts/lib/outcome_report.rb",
+      "scripts/outcome-report" => "scripts/outcome-report",
+      # Intent 336 (G3): ReadySet, the one function that says what may run
+      # next, and its CLI. node-transition requires the lib as of n5;
+      # registered here (rather than waiting for n8's own CLI/doc unit) so
+      # test/install_sync_test.rb stays green across every intermediate unit.
+      "scripts/lib/ready_set.rb" => "scripts/lib/ready_set.rb",
+      "scripts/ready-set" => "scripts/ready-set",
+      # Intent 337 (G4): the roadmap graph model and its tree renderer,
+      # registered as they land (test/installer_core_test.rb requires every
+      # scripts/lib file to be manifest-covered as soon as it exists, not
+      # only once the CLI that ships it arrives at n4).
+      "scripts/lib/roadmap_graph.rb" => "scripts/lib/roadmap_graph.rb",
+      "scripts/lib/graph_tree.rb" => "scripts/lib/graph_tree.rb",
+      "scripts/lib/index_projection.rb" => "scripts/lib/index_projection.rb",
+      "scripts/lib/roadmap_render.rb" => "scripts/lib/roadmap_render.rb",
+      "scripts/lib/roadmap_migration.rb" => "scripts/lib/roadmap_migration.rb",
+      "scripts/roadmap-graph" => "scripts/roadmap-graph",
+      "scripts/index-projection" => "scripts/index-projection",
+      # Intent 338 (G5): the node packet command - the trust-boundary wrapper,
+      # the five-block gatherer/assembler, and the CLI 340's runner calls.
+      "scripts/lib/packet_wrapper.rb" => "scripts/lib/packet_wrapper.rb",
+      "scripts/lib/node_packet.rb" => "scripts/lib/node_packet.rb",
+      "scripts/node-packet" => "scripts/node-packet",
+      # Intent 342 (G9): the backward shim that presents actions/*.md as a
+      # node graph for any legacy intent, so WorkGraphValidator can require
+      # it without going red on contact with install_sync_test.
+      "scripts/lib/action_graph_shim.rb" => "scripts/lib/action_graph_shim.rb",
+      # Intent 340 (G7, n1): the runner command - the subcommand table over
+      # the declared node graph, its shared context (RunnerCore), and the
+      # installed-core integrity check (CoreIntegrity) the runner's trust
+      # boundary and doctor will both call.
+      "scripts/runner" => "scripts/runner",
+      "scripts/lib/runner_core.rb" => "scripts/lib/runner_core.rb",
+      "scripts/lib/core_integrity.rb" => "scripts/lib/core_integrity.rb",
+      # Intent 340 (G7, n2): the merge abort, the reclaim, and the extension -
+      # the first thing every `step` does, routed from scripts/runner's `sweep`
+      # verb.
+      "scripts/lib/runner_sweep.rb" => "scripts/lib/runner_sweep.rb",
+      # Intent 340 (G7, n3): a work node's own git worktree, cut from the
+      # intent branch tip, merged back into the intent branch, and swept once
+      # its node is terminal.
+      "scripts/lib/node_worktree.rb" => "scripts/lib/node_worktree.rb",
+      # Intent 340 (G7, n4): the return schema (NodeReturn) and the six-check
+      # gate (RunnerAbsorb) that turns one executor return into exactly one
+      # node ledger transition, required lazily by scripts/runner's `step`.
+      "scripts/lib/node_return.rb" => "scripts/lib/node_return.rb",
+      "scripts/lib/runner_absorb.rb" => "scripts/lib/runner_absorb.rb",
+      # Intent 340 (G7, n5): validation, policy, leases and the dispatch plan
+      # - RunnerPolicy (the kind table) and RunnerDispatch, required lazily
+      # by scripts/runner's `step`.
+      "scripts/lib/runner_policy.rb" => "scripts/lib/runner_policy.rb",
+      "scripts/lib/runner_dispatch.rb" => "scripts/lib/runner_dispatch.rb",
+      # Intent 340 (G7, n6): answer (closes a decision node or unparks a
+      # work node parked at needs_decision), proposals (mints ids for what
+      # an executor proposed), and rewind (resets the intent branch to a
+      # node's own commit and respins it) - routed from scripts/runner's
+      # `answer` and `rewind` verbs.
+      "scripts/lib/runner_answer.rb" => "scripts/lib/runner_answer.rb",
+      "scripts/lib/runner_proposals.rb" => "scripts/lib/runner_proposals.rb",
+      "scripts/lib/runner_rewind.rb" => "scripts/lib/runner_rewind.rb",
     }
   end
 

package/scripts/lib/intent_screen.rb

@@ -0,0 +1,309 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+# IntentScreen (intent 316) - fills templates/intent-screen.md from one intent's
+# record: the intent file, the tier's INDEX.md, savepoint.md and checklist.md.
+# Every number on the screen comes from here so the session never writes one by
+# eye. Pure: explicit paths in, a Markdown string out; no ENV, no Dir.pwd.
+#
+# Intent 316a fixed three defects the field code inherited into both the plain
+# renderer and the ANSI renderer (scripts/lib/intent_screen_ansi.rb): the
+# Insight row dumping a multi-clause remainder into the note column, an empty
+# "What this means" heading rendering bold with nothing under it, and step
+# text cut mid-sentence. `step_text`, `insight_fields` and `next_fields` are
+# public so the ANSI renderer reuses the exact same trims (D3) rather than
+# re-deriving them and drifting.
+#
+# Harness-agnostic core: no harness assumption lives here.
+module IntentScreen
+  BAR_WIDTH = 20
+  ON = "█"
+  OFF = "░"
+  PLACEHOLDER_SENTINEL = "<!-- plastic:placeholder -->"
+  SECTIONS = %w[Active Future Completed Abandoned].freeze
+  ITEM_RE = /^\s*- \[([ xX])\]\s+(.*)$/
+  # Em dash and en dash added (intent 316a O1e): a checklist item written
+  # "S1 — text" (the em dash every checklist this intent writes, and the one a
+  # reviewer reads, uses) kept its prefix under the old character class and
+  # rendered "S1  [ open ]  S1 — text" on screen. Intent 317a (A1) made the
+  # separator optional with required whitespace: "S1 text" (the shape real
+  # checklists use) kept its label and doubled in next_fields; a bare "S1"
+  # has no following text and stays prose.
+  STEP_PREFIX_RE = /\A(?:Step|S)\s*\d+\s*(?:[-:·—–]\s*|\s+)(?=\S)/i
+  INSIGHT_RE = /\A(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ)\s+·\s+\S+\s+·\s+.+?\s+—\s+(.+)\z/
+  SAVEPOINT_RE = /\A(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ)\s{2,}(\S+)\s{2,}(.+?)\s*\z/
+  # Intent 317, D6: field-2 tokens that are genuine lifecycle stages. A ledger
+  # can also carry non-lifecycle lines (`Lock  takeover: ...`, and 317's own
+  # `Review`/`Commit`); those must never be mistaken for the current stage.
+  # Placed here, clear of STEP_PREFIX_RE above (316a edits that one).
+  LIFECYCLE_STAGES = %w[What Why How Exec Done].freeze
+
+  # True iff a raw savepoint ledger line's field 2 is a genuine lifecycle
+  # stage (post-execution-review finding 5: centralizes what spawn-preamble
+  # and agent-report used to each copy-paste beside the constant above).
+  def self.lifecycle_line?(line)
+    parts = line.to_s.split(/\s{2,}/)
+    parts.length >= 2 && LIFECYCLE_STAGES.include?(parts[1])
+  end
+
+  # Word-boundary truncation caps (intent 316a D3/O1a/O1c). Never a clause
+  # trim: a clause trim on step text destroys a pinned `OPEN:` row
+  # (test/intent_screen_test.rb:171-178) that a mid-sentence cut would eat.
+  INSIGHT_VALUE_MAX = 72
+  INSIGHT_NOTE_MAX = 96
+  NEXT_VALUE_MAX = 72
+  STEP_TEXT_MAX = 110
+
+  # Where a resume lands, from the ledger's last line (the boarding matrix).
+  def self.landing_stage(stage, milestone)
+    case stage
+    when "Done" then "Done"
+    when "What" then "Why"
+    when "Why" then milestone.to_s.include?("spec.md") ? "How" : "Why"
+    when "How" then milestone.to_s.include?("checklist.md") ? "Exec" : "How"
+    when "Exec" then milestone.to_s.include?("outcome.md") ? "ready to complete" : "Exec"
+    else "Why"
+    end
+  end
+
+  def self.intent_dir?(dir)
+    return false unless dir && File.directory?(dir)
+
+    base = File.basename(dir)
+    return false unless base.match?(/\A[0-9][0-9a-z]*--[\w-]+\z/)
+
+    File.exist?(File.join(dir, "#{base}.md"))
+  end
+
+  def self.render(intent_dir:, store_root:, template:)
+    base = File.basename(intent_dir)
+    id = base.split("--", 2).first
+    intent_text = File.read(File.join(intent_dir, "#{base}.md"))
+
+    fields = {}
+    fields.merge!(store_fields(store_root))
+    status, title = index_fields(store_root, id)
+    fields["status"] = status
+    fields["status.note"] = status == "unlisted" ? "no INDEX.md line names this id" : "listed under ## #{status} in INDEX.md"
+    fields["id"] = id
+    fields["name"] = title || fallback_name(intent_text)
+    fields.merge!(savepoint_fields(intent_dir, intent_text))
+    items = checklist_items(intent_dir)
+    fields.merge!(progress_fields(items))
+    fields.merge!(next_fields(items, status, checklist_present: items_present?(intent_dir)))
+    fields.merge!(insight_fields(intent_text))
+    fields["steps.rows"] = steps_rows(items)
+
+    out = template.dup
+    fields.each { |k, v| out = out.gsub("{{#{k}}}", v.to_s) }
+    out.gsub(/\n{3,}/, "\n\n")
+  end
+
+  # --- store ---------------------------------------------------------------------
+
+  def self.store_fields(store_root)
+    parent = File.basename(File.dirname(store_root))
+    if parent == "projects"
+      slug = File.basename(store_root)
+      { "store" => "project:#{slug}", "store.note" => "the #{slug} project store" }
+    else
+      { "store" => "global", "store.note" => "the global store" }
+    end
+  end
+
+  # --- INDEX.md -----------------------------------------------------------------
+
+  def self.index_fields(store_root, id)
+    path = File.join(store_root, "INDEX.md")
+    return ["unlisted", nil] unless File.exist?(path)
+
+    section = nil
+    File.foreach(path) do |line|
+      if line.start_with?("## ")
+        name = line[3..].strip
+        section = SECTIONS.include?(name) ? name : nil
+        next
+      end
+      next unless section && line.strip.start_with?("- [")
+
+      m = line.match(/\A\s*- \[#{Regexp.escape(id)}\s+[-—]\s+(.+?)\]\(/)
+      return [section, m[1].strip] if m
+    end
+    ["unlisted", nil]
+  end
+
+  def self.fallback_name(intent_text)
+    m = intent_text.match(/^intent:\s*["']?(.+?)["']?\s*$/)
+    text = m ? m[1] : ""
+    text.length > 60 ? "#{text[0, 57]}..." : text
+  end
+
+  # --- savepoint.md ---------------------------------------------------------------
+
+  def self.savepoint_fields(intent_dir, intent_text)
+    path = File.join(intent_dir, "savepoint.md")
+    lines = File.exist?(path) ? File.readlines(path).map(&:strip).reject(&:empty?) : []
+    matched = lines.reverse.map { |l| l.match(SAVEPOINT_RE) }.compact
+    last = matched.first
+    unless last
+      return { "stage" => "Why", "stage.note" => "no savepoint line yet",
+               "savepoint" => "none", "savepoint.note" => "" }
+    end
+
+    # D6: the STAGE PICK is guarded to the last LIFECYCLE line (What/Why/How/
+    # Exec/Done), so a trailing Lock/Review/Commit line cannot be mistaken for
+    # the stage. The Savepoint field below still shows the TRUE last line,
+    # whatever its kind - that is what a savepoint is.
+    lifecycle_last = matched.find { |m| LIFECYCLE_STAGES.include?(m[2]) }
+    stage_source = lifecycle_last || last
+
+    ts, stage, milestone = last[1], last[2], last[3]
+    landing = landing_stage(stage_source[2], stage_source[3])
+    delivered = lines.map { |l| l.match(SAVEPOINT_RE) }.compact.map { |m| m[2] }.uniq
+    delivered &= %w[What Why How Exec]
+    note = if landing == "Done"
+             "delivered; the record is immutable"
+           elsif landing == "ready to complete"
+             "outcome.md is real; run the ending procedure"
+           else
+             "#{delivered.join(', ')} delivered; the work is open"
+           end
+    { "stage" => landing, "stage.note" => note,
+      "savepoint" => "#{stage} · #{milestone}", "savepoint.note" => human_time(ts) }
+  end
+
+  def self.human_time(ts)
+    m = ts.match(/\A(\d{4}-\d\d-\d\d)T(\d\d:\d\d)/)
+    m ? "#{m[1]} #{m[2]} UTC" : ts
+  end
+
+  # --- checklist.md --------------------------------------------------------------
+
+  def self.items_present?(intent_dir)
+    path = File.join(intent_dir, "checklist.md")
+    return false unless File.exist?(path)
+
+    !File.read(path).lstrip.start_with?(PLACEHOLDER_SENTINEL)
+  end
+
+  def self.checklist_items(intent_dir)
+    return [] unless items_present?(intent_dir)
+
+    File.readlines(File.join(intent_dir, "checklist.md")).filter_map do |line|
+      m = line.match(ITEM_RE)
+      next unless m
+
+      text = m[2].strip
+      next if text == "..."
+
+      { done: m[1] != " ", text: text.sub(STEP_PREFIX_RE, "") }
+    end
+  end
+
+  def self.progress_fields(items)
+    total = items.length
+    done = items.count { |i| i[:done] }
+    on = total.zero? ? 0 : (done * BAR_WIDTH) / total
+    bar = (ON * on) + (OFF * (BAR_WIDTH - on))
+    note = if total.zero?
+             "no checklist yet"
+           elsif done == total
+             "all steps done"
+           else
+             "#{total - done} steps open"
+           end
+    { "progress.bar" => bar, "progress.done" => done.to_s, "progress.total" => total.to_s,
+      "progress.note" => note }
+  end
+
+  # `escape_pipes:` (intent 316a O1d, default true) keeps the plain Markdown
+  # table's pipe-escaping; the ANSI renderer, which never emits a table,
+  # passes `escape_pipes: false` to get the raw value instead of a literal
+  # `\|`. Named to not shadow the module's own `escape` method.
+  def self.next_fields(items, status, checklist_present:, escape_pipes: true)
+    return { "next" => "", "next.note" => "" } if %w[Completed Abandoned].include?(status)
+    return { "next" => "write checklist.md", "next.note" => "How" } unless checklist_present
+
+    idx = items.index { |i| !i[:done] }
+    return { "next" => "", "next.note" => "all steps done" } unless idx
+
+    head, = split_first_clause(items[idx][:text])
+    head = truncate_words(head, NEXT_VALUE_MAX)
+    head = escape(head) if escape_pipes
+    { "next" => "S#{idx + 1} · #{head}", "next.note" => "first open step" }
+  end
+
+  def self.steps_rows(items)
+    return "| | | no steps yet |" if items.empty?
+
+    items.each_with_index.map do |item, i|
+      "| S#{i + 1} | #{item[:done] ? 'done' : 'open'} | #{escape(step_text(item[:text]))} |"
+    end.join("\n")
+  end
+
+  # Public (intent 316a O1c) so the ANSI renderer trims step text identically:
+  # word-boundary truncation only, never a clause trim, at STEP_TEXT_MAX.
+  def self.step_text(text)
+    truncate_words(text, STEP_TEXT_MAX)
+  end
+
+  def self.escape(text)
+    text.gsub("|", "\\|")
+  end
+
+  # --- ## Insights ----------------------------------------------------------------
+
+  def self.insight_fields(intent_text, escape_pipes: true)
+    section = intent_text.split(/^## Insights\s*$/, 2)[1].to_s.split(/^## /, 2)[0].to_s
+    entry = section.lines.map(&:strip).reverse.map { |l| l.match(INSIGHT_RE) }.compact.first
+    return { "insight" => "none yet", "insight.note" => "" } unless entry
+
+    ts, text = entry[1], entry[2].strip
+    head, tail = split_first_clause(text)
+    value = truncate_words(head, INSIGHT_VALUE_MAX)
+    tail = tail.empty? ? "" : truncate_words(tail, INSIGHT_NOTE_MAX)
+    note = tail.empty? ? human_time(ts) : "#{human_time(ts)} · #{tail}"
+    if escape_pipes
+      { "insight" => escape(value), "insight.note" => escape(note) }
+    else
+      { "insight" => value, "insight.note" => note }
+    end
+  end
+
+  # First clause of `text`, and at most one following clause as the tail.
+  # Anything past the second clause is discarded (intent 316a O1a): the old
+  # behavior dumped the ENTIRE remainder into the note (an 800-character
+  # real-world tail starting mid-list). Boundary is a `.` or `;` immediately
+  # followed by whitespace-then-more or end of string, so "alpha.2" and "2.0"
+  # are never mistaken for clause ends.
+  def self.split_first_clause(text)
+    head, rest = clause_and_rest(text)
+    return [head, ""] unless rest
+
+    second, more = clause_and_rest(rest)
+    tail = more ? second : rest
+    [head, tail]
+  end
+
+  # Returns [clause_without_terminal_punctuation, remainder_or_nil]. `nil` for
+  # the remainder means either no boundary exists at all, or the boundary
+  # sits at the absolute end of `text` (a single trailing clause with nothing
+  # after it) — both cases where there is no SECOND clause to fold in.
+  def self.clause_and_rest(text)
+    m = text.match(/\A(.+?)[.;](\s+(.*)|\z)/m)
+    return [text, nil] unless m
+
+    remainder = m[2].to_s.strip
+    remainder.empty? ? [m[1], nil] : [m[1], remainder]
+  end
+
+  # Word-boundary truncation with a trailing "…" when cut, never mid-word and
+  # never a clause trim (intent 316a D3).
+  def self.truncate_words(text, max)
+    return text if text.length <= max
+    return "…" if max <= 1
+
+    cut = text[0, max - 1].rindex(" ")
+    cut = max - 1 if cut.nil? || cut.zero?
+    "#{text[0, cut].rstrip}…"
+  end
+end