@zalom/plastic 2.0.0-alpha.15 → 2.0.0-alpha.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "2.0.0-alpha.15",
+  "version": "2.0.0-alpha.17",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/hook-message-display

@@ -51,11 +51,18 @@ begin
     tmp_root = ENV["PLASTIC_TMP"].to_s.empty? ? Dir.tmpdir : ENV["PLASTIC_TMP"]
     plastic_home = File.expand_path(ENV["PLASTIC_HOME"] || "~/.plastic")
 
+    # PLASTIC_HOOK_TRACE=<file> (331a1): opt-in, off by default, one JSON
+    # object appended per chunk. This script is the only place allowed to
+    # read the environment; MessageDisplay takes the sink as an argument.
+    trace_path = ENV["PLASTIC_HOOK_TRACE"].to_s
+    trace = trace_path.empty? ? nil : MessageDisplay.file_trace(trace_path)
+
     handler = MessageDisplay.new(
       tmp_root: tmp_root,
       plastic_home: plastic_home,
       color: color_enabled?(plastic_home),
       now: Time.now,
+      trace: trace,
     )
     result = handler.handle(payload)
 

package/scripts/lib/message_display.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "json"
 require_relative "screen_paint"
 
 # MessageDisplay (intent 316a, O4/O5, round 3 concurrency fix) - the Claude
@@ -110,9 +111,13 @@ class MessageDisplay
   # NOSCREEN (D2), never read by this class as a decision in its own right.
   PENDING_FILE = "PENDING"
 
+  # `trace` (331a1): an optional callable taking one Hash per chunk. The class
+  # stays pure - it never reads PLASTIC_HOOK_TRACE, never opens a file of its
+  # own; the CLI reads the variable and injects `file_trace`. nil, the
+  # default, costs the common path one `unless` and nothing else.
   def initialize(tmp_root:, plastic_home:, color:, now:, wait_ms: 300, poll_ms: 20,
                  index_wait_ms: 20, max_wait_ms: 2000,
-                 sleeper: ->(seconds) { sleep(seconds) })
+                 sleeper: ->(seconds) { sleep(seconds) }, trace: nil)
     @tmp_root = tmp_root
     @plastic_home = plastic_home
     @color = color
@@ -122,6 +127,7 @@ class MessageDisplay
     @index_wait_ms = index_wait_ms
     @max_wait_ms = max_wait_ms
     @sleeper = sleeper
+    @trace = trace
   end
 
   def handle(payload)
@@ -141,11 +147,28 @@ class MessageDisplay
 
     dir = self.class.buffer_path(tmp_root: @tmp_root, session_id: session_id, message_id: message_id)
 
-    if index == 0
-      handle_chunk_zero(dir, delta, cwd, final)
-    else
-      handle_later_chunk(dir, index, delta, final)
-    end
+    @trace_detail = {}
+    result =
+      if index == 0
+        handle_chunk_zero(dir, delta, cwd, final)
+      else
+        handle_later_chunk(dir, index, delta, final)
+      end
+
+    emit_trace(index, final, result)
+    result
+  end
+
+  # One row per chunk, only when a sink was injected. Never raises: a trace
+  # is a diagnostic and must not be able to change what the hook returns.
+  def emit_trace(index, final, result)
+    return unless @trace
+
+    row = { "index" => index, "final" => final,
+            "displayed_bytes" => result.is_a?(String) ? result.bytesize : nil }
+    @trace.call(row.merge(@trace_detail.to_h))
+  rescue StandardError
+    nil
   end
 
   # The message directory both this class and the bash launcher (hooks/
@@ -164,6 +187,17 @@ class MessageDisplay
     File.join(buffer_path(tmp_root: tmp_root, session_id: session_id, message_id: message_id), SCREEN_FILE)
   end
 
+  # A trace sink that appends one JSON object per chunk to `path`. Every
+  # failure is swallowed: an unwritable path must never turn a diagnostic
+  # into a broken hook (D5, fail open).
+  def self.file_trace(path)
+    lambda do |row|
+      File.open(path, "a") { |f| f.puts(JSON.generate(row)) }
+    rescue StandardError
+      nil
+    end
+  end
+
   def self.noscreen_path(tmp_root:, session_id:, message_id:)
     File.join(buffer_path(tmp_root: tmp_root, session_id: session_id, message_id: message_id), NOSCREEN_FILE)
   end
@@ -186,10 +220,12 @@ class MessageDisplay
   def handle_chunk_zero(dir, delta, _cwd, final)
     split = split_at_opener(delta)
     unless split
+      @trace_detail["decision"] = "noscreen"
       write_noscreen(dir)
       return nil
     end
 
+    @trace_detail["decision"] = "engage"
     engage(dir, 0, split, final)
   end
 
@@ -199,10 +235,25 @@ class MessageDisplay
   # is already on disk. Only once its own delta carries no opener does it
   # fall back to the original decision-driven wait.
   def handle_later_chunk(dir, index, delta, final)
+    # 331a1: an opener engages only a message that is NOT already a screen.
+    # 331a's late engagement exists for the prose-first reply, where chunk 0
+    # wrote NOSCREEN and a later chunk carries the title; it must not fire
+    # again once SCREEN is on disk. A reply can hold several screens back to
+    # back - the roster is a table then ten cards, the session report is many
+    # delivered screens - and re-engaging on each one returned that chunk's
+    # own prefix as raw Markdown and rewrote the start index, so the final
+    # chunk spliced from the LAST opener and everything before it reached the
+    # terminal unpainted. Inside an engaged message a later opener is simply
+    # content: it is buffered like any other line and the painter, which
+    # already understands a run of screens, lays all of them out.
     split = split_at_opener(delta)
-    return engage(dir, index, split, final) if split
+    if split && !engaged?(dir)
+      @trace_detail["decision"] = "engage"
+      return engage(dir, index, split, final)
+    end
 
     decision = wait_for_decision(dir, gate_delta: final ? nil : delta, index: index)
+    @trace_detail["decision"] = decision.to_s
 
     return nil unless decision == :screen
 
@@ -210,6 +261,10 @@ class MessageDisplay
     final ? finalize_final(dir, index) : ""
   end
 
+  def engaged?(dir)
+    File.exist?(File.join(dir, SCREEN_FILE))
+  end
+
   # Engages the message starting at THIS chunk (whatever its index): writes
   # SCREEN carrying this chunk's index (replacing any NOSCREEN, D2/D6),
   # buffers the opener onward at this chunk's own index, and returns the
@@ -426,6 +481,7 @@ class MessageDisplay
 
     region_stop = ScreenPaint.region_end(lines, start)
     painted = ScreenPaint.paint(lines[start...region_stop].join, color: true, markdown_safe: true)
+    trace_region(buffered, lines, start, region_stop, painted)
     return buffered unless painted
 
     # 331a (D4): a lone CLOSING fence immediately after the painted region is
@@ -445,6 +501,26 @@ class MessageDisplay
     out
   end
 
+  # What the final chunk actually painted, for the opt-in trace: how much was
+  # buffered, where the region ran, and the first line the grammar rejected -
+  # the one fact a terminal capture cannot give you. Computed only when a
+  # sink was injected, so an ordinary run pays nothing.
+  def trace_region(buffered, lines, start, region_stop, painted)
+    return unless @trace
+
+    rejected = ScreenPaint.first_rejected(lines, start)
+    @trace_detail.merge!(
+      "buffered_bytes" => buffered.bytesize,
+      "buffered_lines" => lines.length,
+      "region_start" => start,
+      "region_stop" => region_stop,
+      "painted" => !painted.nil?,
+      "first_rejected_line" => rejected && { "index" => rejected[0], "text" => rejected[1][0, 200] },
+    )
+  rescue StandardError
+    nil
+  end
+
   def write_chunk(dir, index, delta)
     atomic_write(File.join(dir, index.to_s), delta)
   end

package/scripts/lib/report_screen.rb

@@ -577,30 +577,69 @@ module ReportScreen
     rows.compact
   end
 
-  # Intent 331b (plan.md, "The one non-additive edit"): the standalone-token
-  # rule, extracted so `action_file_for` (the plan screen's Action column)
-  # calls the exact same rule as `matching_action_heading` and the two can
-  # never drift on what counts as a match. `matching_action_heading`'s own
-  # signature, return shape and behavior are unchanged (row P16).
-  def self.heading_tokens(heading)
-    heading.to_s.sub(/\A#+\s*/, "").split(/[^A-Za-z0-9]+/)
-  end
-
-  # Rows 25-27: D19 - the label must appear as a standalone token in an action
-  # file heading (any level); the count is the matched section's table rows only.
-  def self.matching_action_heading(intent_dir, label)
+# Intent 331b (plan.md, "The one non-additive edit"): the standalone-token
+# rule, extracted so `action_file_for` (the plan screen's Action column)
+# calls the exact same rule as `matching_action_heading` and the two can
+# never drift on what counts as a match.
+def self.heading_tokens(heading)
+  heading.to_s.sub(/\A#+\s*/, "").split(/[^A-Za-z0-9]+/)
+end
+
+# Rows 25-27: D19/D1r - the label must appear as a standalone token in an
+# action file heading (any level), AND that heading must own at least one
+# matrix data row - a heading that only names the label, with no table
+# beneath it (or a table with a separator but no data row), is skipped and
+# the walk keeps going. Lexicographic path order (D8), then file order.
+#
+# Merge note (322 into alpha, 2026-09-05): 322's table-owning rule and 331b's
+# extracted `heading_tokens` are both kept. The token split now comes from the
+# shared helper so `action_file_for` cannot drift from this walk, while the
+# `table_rows(body).any?` guard stays the thing that decides the match.
+def self.matching_action_heading(intent_dir, label)
+  Dir.glob(File.join(intent_dir, "actions", "*.md")).sort.each do |path|
+    split_by_headings(File.read(path)).each do |heading, body|
+      next unless heading_tokens(heading).include?(label)
+      return [heading, body] if table_rows(body).any?
+      end
+    end
+    [nil, nil]
+  end
+
+  # D3r: the row-cell fallback, for the shape where the label never appears in
+  # a heading at all, only as the first cell of a matrix data row. Restricted
+  # to tables under a heading that names itself a matrix (/matrix/i) - never a
+  # step list or any other table - so it cannot answer for a record that has
+  # no matrix anywhere (the close-gate defeat the plan review measured).
+  # Emphasis (bold/italic/code) is stripped from the compared cell; the count
+  # sums matching rows across every matrix heading, in every action file.
+  def self.matching_matrix_rows(intent_dir, label)
+    count = 0
     Dir.glob(File.join(intent_dir, "actions", "*.md")).sort.each do |path|
       split_by_headings(File.read(path)).each do |heading, body|
-        return [heading, body] if heading_tokens(heading).include?(label)
+        next unless heading.to_s.match?(/matrix/i)
+        table_rows(body).each do |cells|
+          cell = cells[0].to_s.gsub(/[*_`]/, "").strip
+          count += 1 if cell == label
+        end
       end
     end
-    [nil, nil]
+    count
   end
 
+  # D7: a label with no letter never resolves, on either path - it is a
+  # bullet-derived Delivered number (delivered_rows), never a label anyone
+  # wrote, and would otherwise fabricate proof from a numbered heading like
+  # "## 1. What this intent is" or from a numbered matrix row-cell column.
   def self.proven_by(intent_dir, label)
+    return NOT_RECORDED unless label.to_s.match?(/[A-Za-z]/)
+
     _heading, body = matching_action_heading(intent_dir, label)
-    return NOT_RECORDED unless body
-    n = table_rows(body).length
+    if body
+      n = table_rows(body).length
+      return n.positive? ? "#{n} test#{n == 1 ? '' : 's'}" : NOT_RECORDED
+    end
+
+    n = matching_matrix_rows(intent_dir, label)
     n.positive? ? "#{n} test#{n == 1 ? '' : 's'}" : NOT_RECORDED
   end
 

package/scripts/lib/screen_paint.rb

@@ -38,6 +38,19 @@ module ScreenPaint
   STEP_LINE_RE = /\A(S\d+)\s+\[ (open|done) \]\s+(.*)\z/.freeze
   TIMELINE_RE = /\A(\d\d:\d\d)\s{2}(\S+)\s{2}(.*)\z/.freeze
   COUNT_LINE_RE = /\A\d+ open( · .*)?\z/.freeze
+  # 331a1: the session verb prints this note between the delivered screens and
+  # the roster (report_screen.rb, render_session). It is our own output, so the
+  # painter must not reject it - the live hook trace caught the region stopping
+  # dead on it, with the whole roster below reaching the terminal as plain
+  # Markdown. Pinned to the exact shape rather than "any sentence": region_end
+  # exists to stop at the model's own prose, and a loose rule would swallow it.
+  SKIP_NOTE_RE = /\A\d+ completed intents? skipped: .+\z/.freeze
+  # 331a2 (D5, S3): render_session's own rescue card when a directory's delivered screen
+  # raises (report_screen.rb:1466-1468) - our own output, not model prose. The census (331a2)
+  # proved it classified :unknown, orphaning the roster below it in a real reply. `:meta`, not
+  # a new kind: it is a one-line grey note under a title and paint's `:meta` arm reads only
+  # `line.strip`, with no positional dependency.
+  RESCUE_CARD_RE = /\A## \S+ · could not render \(.*\)\z/.freeze
   BOLD_LEAD_RE = /\A\*\*([^*]+)\*\*(.*)\z/.freeze
 
   # Intent 317a1 (D3, D4, D5): the data-table palette. Kind and note columns
@@ -195,11 +208,12 @@ module ScreenPaint
     return :table if text.lstrip.start_with?("|")
     return :bold if BOLD_LEAD_RE.match?(stripped) && text == stripped
     return :meta if idx && opener_idx && idx == opener_idx + 1 && stripped.include?(" · ")
+    return :meta if RESCUE_CARD_RE.match?(stripped)
     return :indented if text.start_with?("  ")
     return :field if FIELD_LINE_RE.match?(text)
     return :step if STEP_LINE_RE.match?(text)
     return :timeline if TIMELINE_RE.match?(text)
-    return :count if COUNT_LINE_RE.match?(stripped)
+    return :count if COUNT_LINE_RE.match?(stripped) || SKIP_NOTE_RE.match?(stripped)
     return :closer if ["None", "not recorded", "No intents in delivery.", "No intents delivered in this session."].include?(stripped)
     :unknown
   end
@@ -207,11 +221,22 @@ module ScreenPaint
   # Where the screen region ends inside a larger message (B10): walk from the
   # opener while every line classifies; the first unknown line - ordinary
   # prose, a prose bullet - is the boundary. Never consumes past the screen.
+  #
+  # 331a1: `opener_idx` tracks the NEAREST preceding opener, not the first
+  # one in the message. A reply can carry several screens back to back - the
+  # roster is a table then ten cards, the session report is many delivered
+  # screens - and `classify`'s positional rule is "the line right after a
+  # title", which means the title above it. Testing every line against the
+  # message's first opener made the timestamp under the SECOND screen
+  # :unknown, and the region stopped there: 30 lines of a 350-line session
+  # report painted, the rest reaching the terminal as plain Markdown.
   def region_end(lines, start_idx)
     i = start_idx + 1
+    opener_idx = start_idx
     while i < lines.length
-      kind = classify(lines[i], idx: i, opener_idx: start_idx)
+      kind = classify(lines[i], idx: i, opener_idx: opener_idx)
       break if kind == :unknown
+      opener_idx = i if kind == :opener
       # A bare "**Section**" head belongs to the screen only when what follows
       # is still grammar; "**What this means**" over prose bullets is the
       # model's own commentary and stays outside, unsplit (B10).
@@ -225,6 +250,22 @@ module ScreenPaint
     i
   end
 
+  # The first line the grammar rejects, walking from the opener under the same
+  # nearest-opener rule region_end uses. Returns [index, line] or nil when the
+  # whole run classifies. 331a1: this is what the opt-in hook trace reports,
+  # so a live run says which line stopped the region instead of leaving it to
+  # be guessed from a terminal capture.
+  def first_rejected(lines, start_idx)
+    opener_idx = start_idx
+    ((start_idx + 1)...lines.length).each do |i|
+      kind = classify(lines[i], idx: i, opener_idx: opener_idx)
+      return [i, lines[i].to_s.rstrip] if kind == :unknown
+
+      opener_idx = i if kind == :opener
+    end
+    nil
+  end
+
   def bare_bold?(line)
     m = BOLD_LEAD_RE.match(line.strip)
     m && m[2].to_s.strip.empty?
@@ -271,8 +312,14 @@ module ScreenPaint
       table.clear
     end
 
+    # 331a1: the same nearest-opener rule region_end uses - a reply carrying
+    # several screens must classify each one's meta line against its own
+    # title, not against the first title in the message.
+    opener_idx = first_idx
+
     lines.each_with_index do |line, idx|
-      kind = classify(line, idx: idx, opener_idx: first_idx)
+      kind = classify(line, idx: idx, opener_idx: opener_idx)
+      opener_idx = idx if kind == :opener
       # Intent 317a1 (O6, D8): the run counter tracks consecutive :indented
       # lines so only the SECOND and later lines under a heading like
       # "**Asked**" grey as a note; a :table line (which `next`s below) must

package/skills/intent-ending/SKILL.md

@@ -67,9 +67,10 @@ fill `## Summary`, `## Delivered`, `## Verification`, `## Follow-ups`. `## Deliv
 `| Row | What |` table: one row per thing delivered, in plain wording a reader
 recognizes, not a method name or an implementation summary (that detail
 belongs in `## Summary`). Each row's label must appear as a standalone token
-in an action-file heading (`### S1 - ...` proves row S1); that heading's
-matrix rows become the row's Proven-by cell on `report-screen delivered`'s
-post-delivery screen. `## Needs you` is the literal None or a
+in an action-file heading that owns the matrix table (`### S1 - ...` with a
+table beneath it proves row S1; a table-less heading naming the label is
+skipped); that heading's matrix rows become the row's Proven-by cell on
+`report-screen delivered`'s post-delivery screen. `## Needs you` is the literal None or a
 `| N | What | Why |` table. On abandon, `## Summary` states the abandonment reason and the trail (see Pivot
 below). A placeholder outcome.md is backfilled from the record instead, with the
 close's disposition and the `--outcome-summary` line as its summary. Also author

package/skills/intent-executing/SKILL.md

@@ -75,7 +75,7 @@ Apply the auto skill's risk rule to the executor's return and the diff: a matrix
 
 Whenever a review verdict returns - the plan review before code, or the post-execution review above - the lead appends a `Review` line: `ruby ~/.plastic/scripts/savepoint-note <intent_dir> --kind Review --text "<verdict, what changed>"` (intent 317, D17). This is the other half of what `report-screen delay` reads.
 
-**The D19 heading convention.** An action file's `## Delivered` row (in `outcome.md`) is proven by whichever `actions/ACTION_N.md` heading carries that row's label as a standalone token - `### Row A -` proves row A, `### S1 -` proves row S1. Write action-file section headings so the label they prove is unambiguous (never a substring another label could also match, like `A` inside `AB`); `report-screen delivered`'s Proven-by column renders `not recorded` when no heading matches.
+**The D19 heading convention.** An action file's `## Delivered` row (in `outcome.md`) is proven by the first `actions/ACTION_N.md` heading that carries that row's label as a standalone token AND owns the matrix table (322 D1r) - `### Row A -` with a table beneath it proves row A, `### S1 -` proves row S1; a heading that only names the label, with no table under it, is skipped. Write action-file section headings so the label they prove is unambiguous (never a substring another label could also match, like `A` inside `AB`); `report-screen delivered`'s Proven-by column renders `not recorded` when no heading owns a matching table and no matrix row cell carries the label either.
 
 ### Step 4: Update Intent and Complete
 Capture observations in `## Insights`. When ALL checklist items are checked:

package/templates/outcome.md

@@ -10,8 +10,11 @@ disposition: delivered|abandoned
 <!-- One row per thing delivered, in plain wording a reader recognizes, not
 an implementation summary; the technical detail belongs in ## Summary. Each
 row's label must appear as a standalone token in an actions/*.md heading
-(for example "### S1 - ..." proves row S1): that heading's matrix rows become
-the row's Proven-by cell on the delivered screen (intent 317 D19, 317a). -->
+that owns the matrix table (for example "### S1 - ..." with a table beneath
+it proves row S1); that heading's matrix rows become the row's Proven-by
+cell on the delivered screen (intent 317 D19, 317a, 322 D1r). A label with no
+owning heading falls back to a matrix row cell that carries it, when one
+under a heading named "matrix" exists (322 D3r). -->
 | Row | What |
 | --- | --- |
 | S1 | ... |