@zalom/plastic 2.0.0-alpha.13 → 2.0.0-alpha.14

package/scripts/lib/roadmap_queue.rb

@@ -34,7 +34,9 @@ class RoadmapQueue
   # Entry line parser, anchored on the status vocabulary rather than end of line, so a trailing
   # parenthetical ("delivering (owner ruling...)") does not defeat the match. Accepts the em
   # dash or a hyphen as the separator; roadmap .md files are store-internal and use the em dash.
-  ENTRY = /\A-\s*\[([ xX])\]\s+(\S+)\s+.*?[—-]\s*(queued|delivering|delivered|abandoned|blocked)\b/.freeze
+  # Intent 331c: group 3 captures the entry's own title text (between the id and the status
+  # separator), so a screen reader has it without a second parser; group 4 (was 3) is the status.
+  ENTRY = /\A-\s*\[([ xX])\]\s+(\S+)\s+(.*?)[—-]\s*(queued|delivering|delivered|abandoned|blocked)\b/.freeze
 
   WAVE_HEADING = /\A###\s+(.+?)\s*\z/.freeze
 
@@ -57,6 +59,21 @@ class RoadmapQueue
     analyze(mode: "which")
   end
 
+  # Intent 331c (D6/R1): the one public reader for ONE roadmap's parsed, INDEX-reconciled shape,
+  # so a screen never carries a second parser that can drift from this class's own grammar. Same
+  # reconciliation (`reconcile`) and the same frontier selection (`frontier_for`, R17) `queue`/
+  # `which` use for the whole tier, scoped to the single file at `path`.
+  def roadmap(path)
+    parsed = reconcile([parse_roadmap(path)]).first
+    {
+      slug: parsed[:slug],
+      path: parsed[:path],
+      grouping: RoadmapSavepoint.grouping_heading(File.read(path)),
+      batches: parsed[:waves],
+      frontier: frontier_for(parsed),
+    }
+  end
+
   private
 
   def analyze(mode:)
@@ -124,7 +141,7 @@ class RoadmapQueue
         current = { heading: m[1], entries: [] }
         waves << current
       elsif current && (em = stripped.match(ENTRY))
-        current[:entries] << { id: em[2], raw_status: em[3].downcase }
+        current[:entries] << { id: em[2], text: em[3].strip, raw_status: em[4].downcase }
       end
     end
     waves

package/scripts/lib/roadmap_savepoint.rb

@@ -66,6 +66,25 @@ module RoadmapSavepoint
     File.read(ledger_path).each_line.filter_map { |line| parse_pair(line) }
   end
 
+  # Public (intent 331c): a roadmap's own ledger, parsed into `[Time, event, detail]` triples in
+  # file order - so a screen reader never re-derives the "<iso>  <event>  <detail>" line shape.
+  # `roadmap_path` is the roadmap `.md` file, never the `.savepoint.md` sibling directly (mirrors
+  # `ledger_path_for`'s own convention). No paired ledger file -> `[]`, never an invented event.
+  def ledger_entries(roadmap_path)
+    ledger_path = ledger_path_for(roadmap_path)
+    return [] unless File.exist?(ledger_path)
+
+    File.readlines(ledger_path).filter_map do |line|
+      parts = line.strip.split(/\s{2,}/, 3)
+      next nil unless parts.length == 3
+      begin
+        [Time.iso8601(parts[0]), parts[1], parts[2]]
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+
   def parse_pair(line)
     parts = line.strip.split(/\s{2,}/)
     parts.length >= 3 ? [parts[1], parts[2]] : nil
@@ -141,11 +160,13 @@ module RoadmapSavepoint
   end
   private_class_method :parse_log_time
 
+  # Public (intent 331c): the Log table on a roadmap's `delivered` screen classifies every
+  # `## Log` line through this same keyword vocabulary, so a screen reader never grows a second
+  # copy of KEYWORD_TABLE.
   def classify_event(text)
     hit = KEYWORD_TABLE.find { |regex, _event| text =~ regex }
     hit && hit[1]
   end
-  private_class_method :classify_event
 
   WAVE_ENTRY = /\A-\s*\[([ xX])\]\s+(\S+)\s+.+—\s*(\S+)\s*\z/.freeze
 
@@ -217,13 +238,21 @@ module RoadmapSavepoint
   # already calling `ledger_path_for`), so this is the smaller diff than a new shared module.
   # Raises MissingGroupingHeading, naming the offending path, when neither heading is present.
   def grouping_section_body(text, path: nil)
-    GROUPING_HEADINGS.each do |heading|
-      m = text.match(/^##\s+#{Regexp.escape(heading)}\s*$(.*?)(?=^##\s|\z)/m)
-      return m[1] if m
+    heading = grouping_heading(text)
+    unless heading
+      raise MissingGroupingHeading,
+            "#{path || '(unknown roadmap file)'}: found neither '## Batches' (canonical) nor " \
+            "'## Waves' (legacy) grouping heading"
     end
-    raise MissingGroupingHeading,
-          "#{path || '(unknown roadmap file)'}: found neither '## Batches' (canonical) nor " \
-          "'## Waves' (legacy) grouping heading"
+    text.match(/^##\s+#{Regexp.escape(heading)}\s*$(.*?)(?=^##\s|\z)/m)[1]
+  end
+
+  # Public (intent 331c): "Batches" or "Waves", whichever grouping heading `text` carries - the
+  # one owner of that label so a screen's own field row (and its entries table's column header)
+  # never hand-picks between them a second way. nil when neither heading is present (mirrors
+  # grouping_section_body's own detection, one call site cheaper than two).
+  def grouping_heading(text)
+    GROUPING_HEADINGS.find { |heading| text.match?(/^##\s+#{Regexp.escape(heading)}\s*$/) }
   end
 
   # Stable dedup on the `(event, detail)` pair, keeping the first occurrence in the given

package/scripts/lib/savepoint.rb

@@ -227,6 +227,18 @@ module Savepoint
     append_savepoint_line(intent_dir, "Commit", text, now)
   end
 
+  # The day the Report kind (below) shipped. `doctor`'s intent_reports_printed_check reads
+  # this so it never re-litigates a ledger recorded before the kind existed (intent 331f, R6).
+  REPORT_KIND_SINCE = "2026-09-05"
+
+  # Append a `Report` line: one per report screen printed (intent 331f, D2/D3). Same primitive
+  # as append_review_savepoint/append_commit_savepoint above, so the line shape, dedup, and
+  # timestamp format never drift. `savepoint_milestone` maps FILENAMES only, so a Report line
+  # is never mistaken for a file-landing lifecycle line by construction.
+  def self.append_report_savepoint(intent_dir, text, now: Time.now)
+    append_savepoint_line(intent_dir, "Report", text, now)
+  end
+
   TERMINAL_DISPOSITIONS = %w[delivered abandoned].freeze
 
   # Append the terminal bookend `Done  delivered|abandoned`, written by the

package/scripts/lib/screen_paint.rb

@@ -17,11 +17,21 @@ require_relative "intent_screen_ansi"
 # markdown_safe are caller arguments, exactly like IntentScreenAnsi before it
 # (316a1); the 318 ceiling holds - the palette is IntentScreenAnsi's, no new
 # colors, no box borders.
+#
+# Intent 331a (D6): a registry, so a new screen KIND is a new file
+# (scripts/lib/screens/<kind>.rb, calling `register` on load), never a diff
+# to this one. `paint:` is optional and defaults to the shared pipeline
+# below - no shipped kind has its own palette; `classify`/`paint` branch on
+# LINE SHAPE, never on kind. The registry's job is only that a new kind's
+# opener is recognized without editing this file, and that a kind CAN
+# supply its own paint lambda on the rare day one needs one.
 module ScreenPaint
   A = IntentScreenAnsi
 
   # A screen's first line: "## ▶ id · name", "## ✔ id · name · delivered",
-  # "▶ In delivery · ...", "✔ id · name · delivered in ...".
+  # "▶ In delivery · ...", "✔ id · name · delivered in ...". Retained for
+  # reference (and as the union every shipped kind below decomposes into);
+  # `classify`/`paint` consult the registry, not this constant, directly.
   OPENER_RE = /\A(?:## )?[▶✔] .+ · /.freeze
 
   FIELD_LINE_RE = /\A(Stage|Next|Changed|Lead|Progress)(\s{2,})(.*)\z/.freeze
@@ -35,11 +45,145 @@ module ScreenPaint
   # text is exactly "not recorded" greys wherever it appears.
   EVIDENCE_PROOF_KINDS = %w[suite red ship doctor deposits verdict].freeze
   EVIDENCE_DEVIATION_KINDS = %w[deviates].freeze
-  NOTE_HEADERS = %w[Source Why].freeze
+  # "Reason" is the current header (D5, intent 331f); "Why" stays too so a screen captured
+  # before the rename still paints (the header map's own forgiving-reader guarantee).
+  NOTE_HEADERS = %w[Source Why Reason].freeze
   NOT_RECORDED = "not recorded"
 
+  # Intent 331f (finding 1, post-exec review): the width bound a column shrink never crosses,
+  # and the glyphs that mark a column as a progress bar, never itself shrunk. Shared with
+  # ReportScreen.fit_table_block (report_screen.rb requires this file, not the other way
+  # around) so a markdown row and a painted row bound their columns the same way.
+  FIT_COLUMN_FLOOR = 8
+  PROGRESS_BAR_CHARS_RE = /[█░]/.freeze
+
+  @registry = {}
+
   module_function
 
+  # Intent 331f1 (spec.md's acceptance rule): the conservative terminal cost used ONLY to
+  # enforce the 115-column bound - ANSI escapes stripped, then every character at or above
+  # U+1100 (the East Asian Wide/Ambiguous threshold; a block glyph like "█"/"░" sits well past
+  # it) counts two columns, everything else one. `IntentScreenAnsi.visible_width` stays a
+  # plain ANSI-stripped `.length` because it drives PADDING, not the bound - a terminal that
+  # draws "█" one column wide would misalign if padding used this conservative cost.
+  # Over-bounding only ever makes a row narrower, never wraps one, so using this rule for the
+  # bound alone is always safe.
+  WIDE_CODEPOINT_MIN = 0x1100
+
+  def display_columns(text)
+    text.to_s.gsub(A::ANSI_RE, "").each_char.sum { |c| c.ord >= WIDE_CODEPOINT_MIN ? 2 : 1 }
+  end
+
+  # Truncate `text` to at most `max_chars` DISPLAY COLUMNS, cutting at the last whitespace at
+  # or before the limit (never mid-word) and appending a single ellipsis when truncation
+  # happens. The one shared implementation (intent 331f, finding 1; intent 331f1 finding A1):
+  # ReportScreen.truncate_on_word_boundary and dashboard.rb's own helper of the same name both
+  # delegate here. The ellipsis (U+2026) itself sits above WIDE_CODEPOINT_MIN, so it costs TWO
+  # display columns even though it is one character - the budget reserves that display width,
+  # not `ellipsis.length`, or every truncated cell lands one column over (finding A1). Any
+  # ellipsis already trailing the word-boundary slice is dropped before the fresh one is
+  # appended, so a value truncated twice (the assembled-row backstop truncating a cell that
+  # was already cut) never stacks a second ellipsis onto the first.
+  def truncate_on_word_boundary(text, max_chars)
+    t = text.to_s
+    return t if display_columns(t) <= max_chars
+    ellipsis = A::ELLIPSIS
+    budget = [max_chars - display_columns(ellipsis), 0].max
+    # Walk characters accumulating DISPLAY columns, not a raw character index: the row-level
+    # backstop calls this on an ALREADY-ASSEMBLED row that can carry several prior per-cell
+    # ellipses (each one two display columns for one character), so a plain `t[0, limit]`
+    # character slice can under-cut and still land over budget once its own wide characters
+    # are counted.
+    cols = 0
+    cut_at = 0
+    t.each_char do |c|
+      w = c.ord >= WIDE_CODEPOINT_MIN ? 2 : 1
+      break if cols + w > budget
+      cols += w
+      cut_at += 1
+    end
+    slice = t[0, cut_at]
+    cut = slice.rindex(/\s/)
+    slice = slice[0, cut] if cut && cut.positive?
+    slice = slice.rstrip
+    slice = slice.chomp(ellipsis) while slice.end_with?(ellipsis)
+    "#{slice}#{ellipsis}"
+  end
+
+  # Shrinks a row of column `widths` until their sum fits `budget`: the widest shrinkable
+  # column loses one column at a time, ties break toward the leftmost column, no column ever
+  # drops below its own `floors[i]` (FIT_COLUMN_FLOOR for every column when `floors` is
+  # omitted, the original behavior), and a column flagged in `bar_columns` (it carries a
+  # progress bar) is never touched regardless of its floor. The one shared shrink (intent
+  # 331f, finding 1; intent 331f1, S3): ReportScreen.fit_table_block's markdown row and
+  # ScreenPaint.paint_data_table's painted row both bound through this rather than carrying
+  # two loops that could drift apart. Returns a new array; the caller's own `widths` is left
+  # untouched.
+  def shrink_column_widths(widths, budget, bar_columns:, floors: nil)
+    floors ||= Array.new(widths.length, FIT_COLUMN_FLOOR)
+    widths = widths.dup
+    loop do
+      break if widths.sum <= budget
+      candidates = widths.each_index.select { |ci| !bar_columns[ci] && widths[ci] > floors[ci] }
+      break if candidates.empty?
+      target = candidates.max_by { |ci| [widths[ci], -ci] }
+      widths[target] -= 1
+    end
+    widths
+  end
+
+  # Intent 331f1, S3 (brief 4): the per-column floor a data-table shrink never crosses - a
+  # column never shrinks below its own header cell, below its natural width when that is at
+  # most 10 columns (the id case: an id column is already narrow, so "natural width" IS its
+  # floor and a uniform 8-column floor could still crush it), or below a bar cell (bar columns
+  # are handled separately, by `bar_columns:` above, but a caller may still pass a natural
+  # width here too - `[header_len, base].max` never fights that).
+  def column_floor(header_len, natural_width)
+    base = natural_width <= 10 ? natural_width : FIT_COLUMN_FLOOR
+    [header_len, base].max
+  end
+
+  # Intent 331f1 (post-execution review, findings P2/P3): a padded cell renders as its column
+  # width (characters, from `ljust`) plus that cell's own DISPLAY overage -
+  # `display_columns(cell) - cell.length` - because a progress-bar glyph or an already-embedded
+  # ellipsis costs more display columns than characters. Crediting overage only to columns
+  # flagged `bar_columns:` (the old rule) misses a padded cell that carries an ellipsis in an
+  # ordinary text column - exactly what ReportScreen.fit_row_cell hands roadmap_state's Intent
+  # column - so the assembled row can still land over the bound even though every column width
+  # was computed correctly. The real cost is per ROW, not per column: `rows_of_cells` is an
+  # array of rows, each an array of already-stripped, not-yet-padded/truncated cell strings, and
+  # this returns the worst row's total overage - the one number ScreenPaint.paint_data_table,
+  # ReportScreen.fit_table_block, and ReportScreen.fit_field_table_block all reserve out of their
+  # budget, so the three renderers spend one rule rather than three copies that can drift.
+  def row_display_overage(rows_of_cells)
+    rows_of_cells.map { |cells| cells.sum { |c| display_columns(c.to_s) - c.to_s.length } }.max || 0
+  end
+
+  # Registers a screen kind's opener grammar (a Regexp or a callable taking
+  # the stripped opener line and returning truthy/falsy), plus an optional
+  # `paint:` lambda for a kind that needs its own palette (`call(text,
+  # color:, width:, markdown_safe:)`). Idempotent by kind: registering the
+  # same kind again replaces its entry rather than adding a second one.
+  def register(kind, opener:, paint: nil)
+    @registry[kind.to_sym] = { opener: opener, paint: paint }
+  end
+
+  # Every registered kind's name, shipped and caller-added alike.
+  def kinds
+    @registry.keys
+  end
+
+  # The first registered kind whose opener matches `text` (an already
+  # stripped, single line), or nil.
+  def opener_kind(text)
+    @registry.find { |_, entry| opener_matches?(entry[:opener], text) }&.first
+  end
+
+  def opener_matches?(opener, text)
+    opener.respond_to?(:call) ? !!opener.call(text) : !!opener.match?(text)
+  end
+
   # The classifier both paint and region_end share. `idx`/`opener_idx` give
   # the positional rule its footing: the line right after a title is the meta
   # line (delivered/delay print one), recognizable by its " · " separators.
@@ -47,7 +191,7 @@ module ScreenPaint
     text = line.chomp
     stripped = text.strip
     return :blank if stripped.empty?
-    return :opener if OPENER_RE.match?(stripped) && text == stripped
+    return :opener if text == stripped && !opener_kind(stripped).nil?
     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?(" · ")
@@ -101,10 +245,20 @@ module ScreenPaint
     lines = text.to_s.lines
     first_idx = lines.index { |l| !l.strip.empty? }
     return nil if first_idx.nil?
+
+    kind = opener_kind(lines[first_idx].strip)
     # Intent 330 (D7/O3.26): a screen that is nothing but a single known
     # closer line (e.g. "No intents delivered in this session.") has no
     # opener to require - it is already the whole, honest message.
-    return nil unless %i[opener closer].include?(classify(lines[first_idx]))
+    return nil unless kind || classify(lines[first_idx]) == :closer
+
+    # Intent 331a (D6): a registered kind MAY supply its own paint lambda;
+    # when it does, this whole call delegates to it instead of the shared
+    # pipeline below. No shipped kind does.
+    if kind
+      custom = @registry[kind][:paint]
+      return custom.call(text, color: color, width: width, markdown_safe: markdown_safe) if custom
+    end
 
     out = +""
     table = []
@@ -185,8 +339,17 @@ module ScreenPaint
     row.split("|", -1).map(&:strip)[1..-2].to_a
   end
 
+  # Intent 331f1 (finding A3): the ONE classifier, called by both this painter and
+  # ReportScreen.fit_table_block's field-vs-data dispatch, so a table is never fitted by one
+  # rule and painted by another. A block is a field table when EVERY non-separator,
+  # non-blank-scaffold row's first cell is bold - not just the first row (the old rule):
+  # a data table whose header cell happens to be bold (e.g. "**Kind**") still has ordinary,
+  # unbold data rows underneath it, so it stays a data table. A block with nothing left after
+  # stripping separators/scaffolding classifies as neither (false).
   def field_table?(rows)
-    rows.first&.gsub(/[\s|]/, "") == "" || cells_of(rows.first).first.to_s.start_with?("**")
+    candidates = rows.reject { |r| SEPARATOR_RE.match?(r) || r.gsub(/[\s|]/, "").empty? }
+    return false if candidates.empty?
+    candidates.all? { |r| cells_of(r).first.to_s.start_with?("**") }
   end
 
   # A field table ("| | | |" scaffold, "| **Key** | value | note |" rows)
@@ -199,11 +362,11 @@ module ScreenPaint
     rows = rows.reject { |r| SEPARATOR_RE.match?(r) || r.gsub(/[\s|]/, "").empty? }
     return "" if rows.empty?
 
-    if cells_of(rows.first).first.to_s.start_with?("**")
+    if field_table?(rows)
       return paint_field_table(rows, color: color, width: width, markdown_safe: markdown_safe)
     end
 
-    paint_data_table(rows, color: color, markdown_safe: markdown_safe)
+    paint_data_table(rows, color: color, width: width, markdown_safe: markdown_safe)
   end
 
   # Intent 317a1 (O3, D9-D11, D14, D15): the same three-column geometry as
@@ -228,17 +391,66 @@ module ScreenPaint
   # bare `widths[ci]`) is the ragged-row guard: `ReportScreen.escape` writes
   # `\|` while `cells_of` still splits on every `|`, so a row can carry more
   # cells than its header without either side ever raising.
-  def paint_data_table(rows, color:, markdown_safe:)
+  #
+  # Intent 331f (finding 1, post-exec review): padding every cell to its column's max across
+  # ALL rows can paint a row wider than `width` even when every plain row on its own measured
+  # under the bound (D7 is on the RENDERED row) - a row short in one column but maximal in
+  # another paints wider than its own plain row ever was. `width` bounds the column widths the
+  # same way ReportScreen.fit_table_block bounds a markdown row's, through the one shared
+  # shrink, before any cell is padded or joined.
+  def paint_data_table(rows, color:, width:, markdown_safe:)
     grid = rows.map { |r| cells_of(r).map { |c| clean(c, markdown_safe) } }
-    widths = grid.first.each_index.map { |i| grid.map { |r| r[i].to_s.length }.max }
+    ncols = grid.first.length
+    widths = (0...ncols).map { |i| grid.map { |r| r[i].to_s.length }.max }
+    bar_columns = (0...ncols).map { |i| grid.any? { |r| r[i].to_s =~ PROGRESS_BAR_CHARS_RE } }
+    # Intent 331f1 (post-exec review, P2/P3): the shared row-overage rule, not a per-column bar
+    # credit - see ScreenPaint.row_display_overage's own comment for why the bar-only credit
+    # missed a padded cell carrying an ellipsis.
+    overage = row_display_overage(grid)
+    # Intent 331f1, S3 (brief 4): per-column minimums - never below the header cell, never
+    # below a natural width of 10 or less (the id case).
+    header_len = (0...ncols).map { |i| grid.first[i].to_s.length }
+    floors = (0...ncols).map { |i| bar_columns[i] ? widths[i] : column_floor(header_len[i], widths[i]) }
+    budget = width - (2 + 2 * (ncols - 1)) - overage
+    widths = shrink_column_widths(widths, budget, bar_columns: bar_columns, floors: floors)
     kind_col = grid.first.first == "Kind" ? 0 : nil
     note_col = grid.first.index { |h| NOTE_HEADERS.include?(h) }
 
     out = +""
     grid.each_with_index do |cols, ri|
       last_ci = cols.length - 1
-      cells = cols.each_with_index.map do |cell, ci|
-        padded = ci == last_ci ? cell.to_s : cell.to_s.ljust(widths[ci] || 0)
+      texts = cols.each_with_index.map do |cell, ci|
+        text = cell.to_s
+        w = widths[ci]
+        text = truncate_on_word_boundary(text, w) if w && text.length > w
+        ci == last_ci ? text : text.ljust(w || 0)
+      end
+
+      # Intent 331f1 (post-exec review, P4): the row-level backstop. Even with every column
+      # pinned at its floor, the assembled PLAIN row can still exceed `width` once padding/bar/
+      # ellipsis overage is counted - shrink the widest SHRINKABLE cell's PLAIN TEXT (never a
+      # bar column, and always before styling, since truncating an already-styled string cuts
+      # ANSI escapes mid-sequence) until the row fits or nothing is left to shrink.
+      loop do
+        row_dw = display_columns(("  " + texts.join("  ")).rstrip)
+        break if row_dw <= width
+        excess = row_dw - width
+        shrinkable = (0...ncols).reject { |ci| bar_columns[ci] }
+        break if shrinkable.empty?
+        target = shrinkable.max_by { |ci| display_columns(texts[ci]) }
+        cur_dw = display_columns(texts[target])
+        # A bare ellipsis alone already costs 2 display columns; below that floor there is
+        # nothing left to cut. Also bail the moment a cut makes no progress (a text already at
+        # or under the ellipsis floor re-truncates to the same "…" forever) - a row this wide
+        # even at every floor is the documented extreme case, not an infinite loop.
+        break if cur_dw <= 2
+        shrunk = truncate_on_word_boundary(texts[target].rstrip, [cur_dw - excess, 2].max)
+        break if display_columns(shrunk) >= cur_dw
+        texts[target] = shrunk
+      end
+
+      cells = texts.each_with_index.map do |padded, ci|
+        cell = cols[ci]
         # An empty cell never gets styled (317a1 post-exec review, finding
         # 1): `A.styled("", ...)` still emits a color-open/RESET pair around
         # nothing visible, and that hides the join separator's own trailing
@@ -276,4 +488,21 @@ module ScreenPaint
   def clean(text, markdown_safe)
     markdown_safe ? A.clean(text) : text
   end
+
+  # --- the five shipped kinds (intent 331a, D6) -----------------------------
+  #
+  # Each opener is a strict subset of OPENER_RE, decomposed by shape rather
+  # than by any per-kind palette: `intent`/`state` share the exact template
+  # line (templates/intent-screen.md and templates/report-state.md both open
+  # with "## ▶ {{id}} · {{name}}"); `delivered` narrows to the "## ✔ id ·
+  # name · delivered" shape report_screen.rb emits; `roster` and `delay`
+  # cover every bare (no "## ") glyph line, which is exactly ScreenPaint's
+  # original, single OPENER_RE decomposed into its "## "-prefixed half and
+  # its bare half - the union is unchanged, so no existing screen stops
+  # being recognized.
+  register(:intent, opener: /\A## [▶✔] .+ · /)
+  register(:state, opener: /\A## [▶✔] .+ · /)
+  register(:delivered, opener: /\A## ✔ .+ · /)
+  register(:roster, opener: /\A▶ .+ · /)
+  register(:delay, opener: /\A✔ .+ · /)
 end

package/scripts/lib/screens/dashboard.rb

@@ -0,0 +1,20 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "../screen_paint"
+
+# The dashboard screen kind (intent 331d, D4). Its opener is a stricter
+# subset of the already-registered :intent opener (screen_paint.rb:337,
+# registered first), so ScreenPaint.opener_kind never actually answers
+# :dashboard on a live paint call - that is deliberate (R2): :dashboard is
+# tested on its OWN grammar (the OPENER constant below), never on
+# opener_kind's answer, which cannot fail meaningfully here. No custom paint
+# lambda (R3): every line of the screen classifies under the shared
+# field-table/data-table grammar ScreenPaint.paint already carries.
+module Screens
+  module Dashboard
+    OPENER = /\A## ▶ (?:global|project:[a-z0-9][a-z0-9_-]*) · dashboard\z/.freeze
+  end
+end
+
+ScreenPaint.register(:dashboard, opener: Screens::Dashboard::OPENER)

package/scripts/lib/screens/plan.rb

@@ -0,0 +1,18 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "../screen_paint"
+
+# Intent 331b (D2/D4): the plan screen's grammar - "## ▶ {id} · {name} ·
+# plan" - registers through 331a's kind registry, a file under
+# scripts/lib/screens/ rather than a diff to screen_paint.rb. F1 (spec.md):
+# opener_kind answers the FIRST registered match, and :intent's own opener
+# (/\A## [▶✔] .+ · /) already matches this title, so this kind's opener is
+# never actually reached - it still names the kind's home and its true
+# grammar, and that is fine, because paint: nil is what D4's "with the state
+# palette" asks for anyway: the shared pipeline branches on LINE SHAPE, never
+# on kind, and no shipped kind carries its own palette. Narrowing :intent's
+# opener from this file to reach a :plan-specific paint lambda is exactly
+# the forbidden loophole spec.md's F1 names - it would silently un-paint the
+# intent and state screens for every other caller, so it never happens here.
+ScreenPaint.register(:plan, opener: /\A## ▶ .+ · plan\z/, paint: nil)

package/scripts/lib/screens/roadmap.rb

@@ -0,0 +1,15 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "../screen_paint"
+
+# Intent 331c (D7): the roadmap screen kinds. A new screen kind is a file, never a diff to
+# screen_paint.rb (331a's registry, D6): registers `:roadmap_plan`, `:roadmap_state`, and
+# `:roadmap_delivered`, openers that are strict subsets of the shipped intent/delivered openers
+# (`## ▶ ... · roadmap · plan`, `## ▶ ... · roadmap`, `## ✔ ... · roadmap · delivered`), exactly
+# as 331a's five shipped kinds already overlap each other. No `paint:` lambda is supplied: the
+# palette stays IntentScreenAnsi's shared pipeline (the 318 ceiling) - screen_paint.rb's body is
+# not touched by this file.
+ScreenPaint.register(:roadmap_plan, opener: /\A## ▶ .+ · roadmap · plan\z/)
+ScreenPaint.register(:roadmap_state, opener: /\A## ▶ .+ · roadmap\z/)
+ScreenPaint.register(:roadmap_delivered, opener: /\A## ✔ .+ · roadmap · delivered\z/)

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/report-screen

@@ -2,19 +2,21 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-# report-screen - the four delivery-report screens: mid-delivery state,
-# post-delivery delivered, and delay (intent 317), plus session, the whole of
-# one session's delivered work followed by the roster (intent 330). Each fills
-# from the record via scripts/lib/report_screen.rb; no number here is written
-# by eye.
+# report-screen - the pre-delivery plan (intent 331b), the four delivery
+# reports: mid-delivery state, post-delivery delivered, and delay (intent
+# 317), plus session, the whole of one session's delivered work followed by
+# the roster (intent 330). Each fills from the record via
+# scripts/lib/report_screen.rb; no number here is written by eye.
 #
 # Usage:
+#   report-screen plan <intent_dir> [--ansi]
 #   report-screen state <intent_dir> [--changed "<text>"] [--ansi]
 #   report-screen state --all <store_root> [--changed "<text>"] [--ansi]
 #   report-screen delivered <intent_dir> [--ansi] [--repo <dir>]
 #   report-screen delay <intent_dir> [--ansi]
 #   report-screen session <tier_root> [--session <id>] [--since <iso>]
 #                                     [--ledger-root <dir>] [--ansi]
+#   report-screen roadmap <roadmap.md> plan|state|delivered [--ansi] [--store-root <dir>]
 #
 # --ansi delegates to ScreenPaint (intent 317a, D1), the parser/re-layouter
 # in the shared TUI core. Selection is by capability, never by harness:
@@ -34,6 +36,13 @@ require_relative "lib/intent_screen"
 require_relative "lib/screen_paint"
 require_relative "lib/session_ledger"
 
+# Intent 331a (D6/R8): every caller-added screen kind file registers itself
+# on load (ScreenPaint.register), so this glob is the ONLY wiring a new kind
+# needs - no edit here, no edit to screen_paint.rb. Sorted for a
+# deterministic load order; tolerates the directory being absent or empty
+# (Dir.glob answers [] either way), which is this repo's own state today.
+Dir.glob(File.join(__dir__, "lib", "screens", "*.rb")).sort.each { |f| require_relative f }
+
 def usage_abort(message)
   warn "report-screen: #{message}"
   exit 2
@@ -119,6 +128,7 @@ repo_flag = nil
 session_flag = nil
 since_flag = nil
 ledger_root_flag = nil
+store_root_flag = nil
 positional = []
 
 while (arg = args.shift)
@@ -140,13 +150,15 @@ while (arg = args.shift)
     since_flag = args.shift or usage_abort("--since needs a value")
   when "--ledger-root"
     ledger_root_flag = args.shift or usage_abort("--ledger-root needs a path")
+  when "--store-root"
+    store_root_flag = args.shift or usage_abort("--store-root needs a path")
   else
     usage_abort("unknown flag #{arg.inspect}") if arg.start_with?("--") && arg != "--all"
     positional << arg
   end
 end
 
-usage_abort("usage: report-screen state|delivered|delay|session <intent_dir> [--changed \"<text>\"] [--ansi]") unless verb
+usage_abort("usage: report-screen plan|state|delivered|delay|session <intent_dir> [--changed \"<text>\"] [--ansi]") unless verb
 
 all_mode = positional.delete("--all") ? true : false
 target = positional.first
@@ -160,6 +172,16 @@ def paint(text, ansi_enabled, _renderer_path = nil)
 end
 
 case verb
+when "plan"
+  usage_abort("usage: report-screen plan <intent_dir> [--ansi]") unless target
+  intent_dir = File.expand_path(target)
+  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/report-plan.md", __dir__)
+  usage_abort("template not found at #{template_path}") unless File.exist?(template_path)
+  out = ReportScreen.render_plan(intent_dir: intent_dir, store_root: store_root,
+                                  template: File.read(template_path))
+  $stdout.write paint(out, ansi_enabled)
 when "state"
   if all_mode
     usage_abort("usage: report-screen state --all <store_root>") unless target
@@ -233,8 +255,20 @@ when "session"
     note: note, now: now, painter: ->(text) { paint(text, ansi_enabled) }
   )
   $stdout.write out
+when "roadmap"
+  usage_abort("usage: report-screen roadmap <roadmap.md> plan|state|delivered [--ansi] [--store-root <dir>]") if positional.empty?
+  roadmap_path = File.expand_path(positional[0])
+  usage_abort("#{roadmap_path} does not exist") unless File.exist?(roadmap_path)
+  sub_verb = positional[1]
+  usage_abort("usage: report-screen roadmap <roadmap.md> plan|state|delivered") unless sub_verb
+  unless %w[plan state delivered].include?(sub_verb)
+    usage_abort("unknown sub-verb #{sub_verb.inspect} (use plan|state|delivered)")
+  end
+  roadmap_store_root = store_root_flag ? File.expand_path(store_root_flag) : nil
+  out = ReportScreen.render_roadmap(path: roadmap_path, verb: sub_verb, store_root: roadmap_store_root)
+  $stdout.write paint(out, ansi_enabled)
 else
-  usage_abort("unknown verb #{verb.inspect} (use state|delivered|delay|session)")
+  usage_abort("unknown verb #{verb.inspect} (use plan|state|delivered|delay|session|roadmap)")
 end
 
 exit 0