@zalom/plastic 2.0.0-alpha.7 → 2.0.0-alpha.9

package/scripts/lib/screen_paint.rb

@@ -0,0 +1,218 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "intent_screen_ansi"
+
+# ScreenPaint (intent 317a, D1) - the paint seam 317's Needs-you named. Parses
+# the plain Markdown screens our own renderers emit (intent, state, roster,
+# delivered, delay) and re-lays them out in the shipped intent-screen ANSI
+# vocabulary. A parser and RE-LAYOUTER, not a colorizer (A5): the plain
+# screens are pipe tables whose scaffolding rows only disappear under a
+# Markdown renderer, so the painter drops them and rebuilds the layout;
+# content-survival is the contract - every value and note survives, nothing
+# is invented, and text it does not recognize returns nil so every caller
+# fails open to plain.
+#
+# Harness-agnostic core: no harness assumption lives here. No ENV, no TTY. Color, width, and
+# 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.
+module ScreenPaint
+  A = IntentScreenAnsi
+
+  # A screen's first line: "## ▶ id · name", "## ✔ id · name · delivered",
+  # "▶ In delivery · ...", "✔ id · name · delivered in ...".
+  OPENER_RE = /\A(?:## )?[▶✔] .+ · /.freeze
+
+  FIELD_LINE_RE = /\A(Stage|Next|Changed|Lead|Progress)(\s{2,})(.*)\z/.freeze
+  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
+  BOLD_LEAD_RE = /\A\*\*([^*]+)\*\*(.*)\z/.freeze
+
+  module_function
+
+  # 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.
+  def classify(line, idx: nil, opener_idx: nil)
+    text = line.chomp
+    stripped = text.strip
+    return :blank if stripped.empty?
+    return :opener if OPENER_RE.match?(stripped) && text == stripped
+    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 :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 :closer if ["None", "not recorded", "No intents in delivery."].include?(stripped)
+    :unknown
+  end
+
+  # 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.
+  def region_end(lines, start_idx)
+    i = start_idx + 1
+    while i < lines.length
+      kind = classify(lines[i], idx: i, opener_idx: start_idx)
+      break if kind == :unknown
+      # 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).
+      if kind == :bold && bare_bold?(lines[i]) && !grammar_follows?(lines, i, start_idx)
+        break
+      end
+      i += 1
+    end
+    # Trailing blanks belong to the message, not the screen.
+    i -= 1 while i > start_idx + 1 && lines[i - 1].strip.empty?
+    i
+  end
+
+  def bare_bold?(line)
+    m = BOLD_LEAD_RE.match(line.strip)
+    m && m[2].to_s.strip.empty?
+  end
+
+  def grammar_follows?(lines, idx, opener_idx)
+    j = idx + 1
+    j += 1 while j < lines.length && lines[j].strip.empty?
+    return false if j >= lines.length
+    kind = classify(lines[j], idx: j, opener_idx: opener_idx)
+    kind != :unknown && kind != :opener
+  end
+
+  # The painter. Returns the ANSI (or plain re-laid, when color: false) text,
+  # or nil when the input does not open with a screen title or carries a line
+  # outside the grammar - the caller's cue to print the original untouched.
+  def paint(text, color: true, width: A::DEFAULT_WIDTH, markdown_safe: false)
+    lines = text.to_s.lines
+    first_idx = lines.index { |l| !l.strip.empty? }
+    return nil if first_idx.nil?
+    return nil unless classify(lines[first_idx]) == :opener
+
+    out = +""
+    table = []
+    ok = true
+
+    flush = lambda do
+      next if table.empty?
+      out << paint_table(table, color: color, width: width, markdown_safe: markdown_safe)
+      table.clear
+    end
+
+    lines.each_with_index do |line, idx|
+      kind = classify(line, idx: idx, opener_idx: first_idx)
+      if kind == :table
+        table << line.strip
+        next
+      end
+      flush.call
+      case kind
+      when :opener
+        t = clean(line.strip.sub(/\A## /, ""), markdown_safe)
+        out << A.fit(t, width) { |s| A.styled(s, color, A::BOLD, A::NEARWHITE) } << "\n"
+      when :meta
+        out << A.fit(clean(line.strip, markdown_safe), width) { |s| A.styled(s, color, A::MIDGREY) } << "\n"
+      when :bold
+        m = BOLD_LEAD_RE.match(line.strip)
+        head = A.styled(clean(m[1], markdown_safe), color, A::BOLD, A::NEARWHITE)
+        out << head << clean(m[2], markdown_safe) << "\n"
+      when :indented
+        out << A.fit_plain(clean(line.chomp, markdown_safe), width) << "\n"
+      when :field
+        m = FIELD_LINE_RE.match(line.chomp)
+        out << A.styled(m[1].ljust(8), color, A::BOLD) << "  " << clean(m[3], markdown_safe) << "\n"
+      when :step
+        m = STEP_LINE_RE.match(line.chomp)
+        badge = A.status_cell(m[2] == "done", color)
+        out << "#{m[1].ljust(4)} [#{badge}]  #{A.fit_plain(clean(m[3], markdown_safe), width - 12)}\n"
+      when :timeline
+        m = TIMELINE_RE.match(line.chomp)
+        out << A.styled(m[1], color, A::MIDGREY) << "  " << A.styled(m[2].ljust(6), color, A::BOLD) \
+            << "  " << clean(m[3], markdown_safe) << "\n"
+      when :count
+        out << A.fit(line.strip, width) { |s| A.styled(s, color, A::MIDGREY) } << "\n"
+      when :closer
+        out << A.styled(line.strip, color, A::MIDGREY) << "\n"
+      when :blank
+        out << "\n"
+      else
+        ok = false
+        break
+      end
+    end
+    flush.call
+    return nil unless ok
+
+    paint_bars(out.gsub(/\n{3,}/, "\n\n"), color)
+  end
+
+  # --- tables -----------------------------------------------------------------
+
+  SEPARATOR_RE = /\A\|[\s:|-]+\|?\z/.freeze
+
+  def cells_of(row)
+    row.split("|", -1).map(&:strip)[1..-2].to_a
+  end
+
+  def field_table?(rows)
+    rows.first&.gsub(/[\s|]/, "") == "" || cells_of(rows.first).first.to_s.start_with?("**")
+  end
+
+  # A field table ("| | | |" scaffold, "| **Key** | value | note |" rows)
+  # re-lays as the intent screen's vertical field block: bold key, value,
+  # mid-grey note on its own line. A data table re-lays as padded columns
+  # with a bold header, done/open cells colored, no pipes anywhere.
+  def paint_table(rows, color:, width:, markdown_safe:)
+    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?("**")
+      out = +""
+      key_w = rows.map { |r| cells_of(r).first.to_s.gsub("*", "").length }.max
+      rows.each do |row|
+        key, value, note = cells_of(row)
+        key = key.to_s.gsub("*", "")
+        out << "  #{A.styled(key.ljust(key_w), color, A::BOLD)}  #{clean(value.to_s, markdown_safe)}\n"
+        next if note.to_s.empty?
+        out << (" " * (key_w + 4)) << A.fit(clean(note, markdown_safe), width - key_w - 4) { |s| A.styled(s, color, A::MIDGREY) } << "\n"
+      end
+      return out
+    end
+
+    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 }
+    out = +""
+    grid.each_with_index do |cols, ri|
+      cells = cols.each_with_index.map do |cell, ci|
+        padded = cell.to_s.ljust(widths[ci])
+        if ri.zero?
+          A.styled(padded, color, A::BOLD)
+        elsif cell == "done"
+          A.styled(padded, color, A::TEAL)
+        elsif cell == "open"
+          A.styled(padded, color, A::AMBER)
+        else
+          padded
+        end
+      end
+      out << "  " << cells.join("  ").rstrip << "\n"
+    end
+    out
+  end
+
+  def paint_bars(text, color)
+    return text unless color
+    text.gsub(/█+/) { |run| "#{A::TEAL}#{run}#{A::RESET}" }
+        .gsub(/░+/) { |run| "#{A::MIDGREY}#{run}#{A::RESET}" }
+  end
+
+  def clean(text, markdown_safe)
+    markdown_safe ? A.clean(text) : text
+  end
+end

package/scripts/report-screen

@@ -0,0 +1,120 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# report-screen - the three delivery-report screens (intent 317): mid-delivery
+# state, post-delivery delivered, and delay. Each fills from the record via
+# scripts/lib/report_screen.rb; no number here is written by eye.
+#
+# Usage:
+#   report-screen state <intent_dir> [--changed "<text>"] [--ansi]
+#   report-screen state --all <store_root> [--changed "<text>"] [--ansi]
+#   report-screen delivered <intent_dir> [--ansi]
+#   report-screen delay <intent_dir> [--ansi]
+#
+# --ansi delegates to ScreenPaint (intent 317a, D1), the parser/re-layouter
+# in the shared TUI core. Selection is by capability, never by harness:
+# NO_COLOR forces plain, a non-TTY stdout stays plain unless
+# PLASTIC_FORCE_COLOR=1 (the test seam), and an unparseable screen falls
+# open to the plain text untouched.
+#
+# Exit codes:
+#   0 - the screen is on stdout
+#   2 - usage error, or the path/store is not what the verb expects (one line
+#       on stderr, stdout empty)
+
+require_relative "lib/report_screen"
+require_relative "lib/intent_screen"
+require_relative "lib/screen_paint"
+
+def usage_abort(message)
+  warn "report-screen: #{message}"
+  exit 2
+end
+
+# The one place allowed to shell out (D2/D20): resolves the nearest git tag
+# reachable from the repo this script lives in, so `render_delivered`'s
+# version field and the `ship` evidence row are never invented. The pure
+# module never reads git itself; this is injected as `tag_reader:`.
+def git_tag_reader(repo_root)
+  lambda do |_intent_dir|
+    return nil unless File.exist?(File.join(repo_root, ".git"))
+    tag = `git -C #{repo_root} describe --tags --abbrev=0 2>/dev/null`.strip
+    tag.empty? ? nil : tag
+  end
+end
+
+args = ARGV.dup
+verb = args.shift
+changed = nil
+ansi = false
+template_path = nil
+positional = []
+
+while (arg = args.shift)
+  case arg
+  when "--changed"
+    usage_abort("--changed needs a value") if args.empty?
+    changed = args.shift
+  when "--ansi"
+    ansi = true
+  when "--all"
+    positional << "--all"
+  when "--template"
+    template_path = args.shift or usage_abort("--template 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 <intent_dir> [--changed \"<text>\"] [--ansi]") unless verb
+
+all_mode = positional.delete("--all") ? true : false
+target = positional.first
+
+ansi_enabled = ansi && ENV["NO_COLOR"].to_s.empty? &&
+               ($stdout.tty? || ENV["PLASTIC_FORCE_COLOR"] == "1")
+
+def paint(text, ansi_enabled, _renderer_path = nil)
+  return text unless ansi_enabled
+  ScreenPaint.paint(text, color: true) || text
+end
+
+case verb
+when "state"
+  if all_mode
+    usage_abort("usage: report-screen state --all <store_root>") unless target
+    store_root = File.expand_path(target)
+    usage_abort("#{store_root} is not a store (no INDEX.md)") unless File.exist?(File.join(store_root, "INDEX.md"))
+    out = ReportScreen.render_roster(store_root, changed: changed)
+    $stdout.write paint(out, ansi_enabled)
+  else
+    usage_abort("usage: report-screen state <intent_dir> [--changed \"<text>\"]") 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-state.md", __dir__)
+    usage_abort("template not found at #{template_path}") unless File.exist?(template_path)
+    out = ReportScreen.render_state(intent_dir: intent_dir, store_root: store_root, changed: changed,
+                                     template: File.read(template_path))
+    $stdout.write paint(out, ansi_enabled)
+  end
+when "delivered"
+  usage_abort("usage: report-screen delivered <intent_dir>") unless target
+  intent_dir = File.expand_path(target)
+  usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
+  repo_root = File.expand_path("..", __dir__)
+  out = ReportScreen.render_delivered(intent_dir: intent_dir, tag_reader: git_tag_reader(repo_root))
+  $stdout.write paint(out, ansi_enabled)
+when "delay"
+  usage_abort("usage: report-screen delay <intent_dir>") unless target
+  intent_dir = File.expand_path(target)
+  usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
+  out = ReportScreen.render_delay(intent_dir: intent_dir)
+  $stdout.write paint(out, ansi_enabled)
+else
+  usage_abort("unknown verb #{verb.inspect} (use state|delivered|delay)")
+end
+
+exit 0

package/scripts/savepoint-note

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# savepoint-note - the writer CLI for the two savepoint kinds intent 317 adds:
+# Review (one line per plan-review or post-execution-review verdict) and
+# Commit (one line per commit landing during Exec). D17: there is no automatic
+# seam for either (session-commit writes the day ledger, not the intent
+# ledger; the executor's own commits are plain git), so this is an explicit
+# thin wrapper on Savepoint.append_review_savepoint / append_commit_savepoint.
+#
+# Usage:
+#   savepoint-note <intent_dir> --kind Review|Commit --text "<text>"
+#
+# --text is normalized (D21): runs of two or more spaces collapse to one, so a
+# free-text kind that happens to contain a double space cannot key the dedup
+# primitive's split(/\s{2,}/) on the prefix alone and silently drop a later
+# line. A newline in --text is refused outright (exit 2, ledger unchanged)
+# rather than silently splitting one entry into two malformed ledger lines.
+#
+# Exit codes:
+#   0 - the line was appended (or was already recorded; both are success)
+#   2 - usage error, bad --kind, missing --text, a newline in --text, or the
+#       path is not an intent directory (one line on stderr, ledger unchanged)
+
+require_relative "lib/savepoint"
+
+def usage_abort(message)
+  warn "savepoint-note: #{message}"
+  exit 2
+end
+
+args = ARGV.dup
+kind = nil
+text = nil
+positional = []
+while (arg = args.shift)
+  case arg
+  when "--kind"
+    kind = args.shift
+  when "--text"
+    text = args.shift
+  else
+    usage_abort("unknown flag #{arg.inspect}") if arg.start_with?("--")
+    positional << arg
+  end
+end
+
+usage_abort("usage: savepoint-note <intent_dir> --kind Review|Commit --text \"<text>\"") unless positional.length == 1
+
+intent_dir = File.expand_path(positional.first)
+usage_abort("#{intent_dir} is not an intent directory") unless File.exist?(Savepoint.intent_file(intent_dir))
+
+KINDS = %w[Review Commit].freeze
+usage_abort("--kind must be one of #{KINDS.join(', ')}, got #{kind.inspect}") unless KINDS.include?(kind)
+usage_abort("--text is required") if text.nil? || text.empty?
+usage_abort("--text must not contain a newline") if text.include?("\n")
+
+normalized = text.gsub(/ {2,}/, " ").strip
+usage_abort("--text is empty after normalization") if normalized.empty?
+
+case kind
+when "Review" then Savepoint.append_review_savepoint(intent_dir, normalized)
+when "Commit" then Savepoint.append_commit_savepoint(intent_dir, normalized)
+end
+
+exit 0

package/scripts/spawn-preamble

@@ -24,6 +24,7 @@
 
 require_relative "lib/savepoint"
 require_relative "lib/worktree"
+require_relative "lib/intent_screen"
 
 # Verbatim honoring instruction. Kept as one constant so the contract doc and the
 # test assert against the exact same string.
@@ -115,11 +116,17 @@ STAGE_LABELS = {
   "exec" => "Exec", "done" => "Done"
 }.freeze
 
+# Intent 317, D6: a dispatched agent's "Current stage:" line must name the last
+# LIFECYCLE line (What/Why/How/Exec/Done), never a trailing Lock/Review/Commit
+# line - the bug spawn-preamble shared with IntentScreen.savepoint_fields
+# before this guard (plan review finding B1).
 def current_stage(intent_dir)
   ledger = File.join(intent_dir, Savepoint::SAVEPOINT_FILE)
   if File.exist?(ledger)
-    last = File.read(ledger).each_line.map(&:strip).reject(&:empty?).last
-    return last if last
+    lines = File.read(ledger).each_line.map(&:strip).reject(&:empty?)
+    lifecycle = lines.select { |l| IntentScreen.lifecycle_line?(l) }
+    return lifecycle.last if lifecycle.any?
+    return lines.last if lines.any?
   end
   STAGE_LABELS.fetch(Savepoint.derive_stage(intent_dir), Savepoint.derive_stage(intent_dir))
 end

package/skills/auto/SKILL.md

@@ -200,9 +200,10 @@ Then How.
    into the spec, the matrix, and the tests; record what was dropped and why in the action
    file's review fold. A REVISE verdict is folded and not re-reviewed unless a finding changes
    a decision.
-5. Notify the user (the one mid-flight briefing, per `references/human-report-contract.md`):
-   State, the plan shape and what it builds; Risk, the riskiest row of the matrix; Call,
-   proceeding to build. In auto mode this briefing informs; it does not wait.
+5. Print `ruby ~/.plastic/scripts/report-screen state <intent_dir> --changed "How written, plan review next"`
+   (D15; see `references/human-report-contract.md` for the full trigger list). This replaces
+   the old prose State/Risk/Call briefing at this boundary. In auto mode the screen informs;
+   it does not wait.
 
 Then Exec.
 
@@ -252,7 +253,8 @@ every choice is non-destructive and the team has full autonomy.
 Read `../plastic-conventions/references/completion-and-done.md` for what "intent done" means.
 
 1. Verify every checklist item is checked and the suite is green once on the branch.
-2. Write `outcome.md` from `~/.plastic/templates/outcome.md` with `disposition: delivered`.
+2. Write `outcome.md` from `~/.plastic/templates/outcome.md` with `disposition: delivered`,
+   `## Delivered` as the labeled table whose row labels match the action-file headings (317a).
 3. Release, if configured: match the working directory against `~/.plastic/projects.yml`, read
    `project.yml`'s `release` block, and act on `on_complete` (`commit`, `commit_and_push`,
    `manual`), `verify` (green proceeds; red follows `on_red`: `fix_and_retry` up to twice,
@@ -272,6 +274,8 @@ Read `../plastic-conventions/references/completion-and-done.md` for what "intent
    first, or pass `--discard-worktree-changes` deliberately); 3 means the lock survived the
    disarm (`/plastic-doctor check the lock status`); 6 means the structure check refused. Never
    leave an orphaned worktree; run `git worktree prune` on a stale reference.
+6. Print `ruby ~/.plastic/scripts/report-screen delivered <intent_dir>` once (D15): this is the
+   owner report at End, replacing the old prose Done briefing.
 
 ## Error Handling
 
@@ -284,8 +288,8 @@ leaves the project broken.
 
 - Read `references/agent-architecture.md` for the team model, the risk list, the headless note,
   and the solo fallback when dispatching or when a harness has no agent dispatch.
-- Read `references/human-report-contract.md` for the State/Risk/Call briefing before sending the
-  How briefing.
+- Read `references/human-report-contract.md` for the three report screens and the five
+  triggers before printing the How or Completion screen above.
 - Read `references/agent-report-contract.md` for the completion report format when reading a
   dispatched agent's return or synthesizing one.
 - Read `references/end-tail.md` for what `Arm.disarm` does at the End tail and why the reindex

package/skills/auto/references/human-report-contract.md

@@ -1,72 +1,78 @@
-# Human Report Contract (per-stage EM-to-CTO briefing)
-
-This doc defines how the orchestrator briefs the human at each of the five stage boundaries
-(What, Why, How, Exec, Done) in auto mode; for small work only the How boundary fires (see
-`## Depth for small work`). It is the outward, human-facing counterpart to the
-internal report contract in `references/agent-report-contract.md`. Voice: an engineering
-manager briefing a CTO. Lead with impact, name the risk, leave the decision.
-
-## The skeleton
-
-One fixed 3-line shape, reused at every stage:
-
-1. **State**: what happened and what it means, impact first, one line.
-2. **Risk**: the one thing that could bite, or "nothing flagged."
-3. **Call**: the decision left to you, or the go-ahead I am taking.
-
-This is a shape, not a rigid template. Keep the order (State, then Risk, then Call) and keep it
-short. The words can flex to fit the stage.
-
-## Per-stage content
-
-- **What**: State = the work I picked up and why it matters now. Risk = scope uncertainty.
-  Call = confirm this is worth doing, or I proceed.
-- **Why**: State = the approach I chose, one line. Risk = the main trade-off. Call = the one
-  decision I need (approve, or pick an option).
-- **How**: State = the plan shape (task count and what it builds). Risk = the riskiest task or
-  dependency. Call = approve the plan to build.
-- **Exec**: State = what got built and the test result. Risk = residual failures or deviations.
-  Call = go to review, or done.
-- **Done**: State = the delivered impact. Risk = residual risk. Call = the decision left to you
-  (merge, release, accept).
+# Human Report Contract (the three report screens, intent 317)
+
+D15: the prose EM-to-CTO briefing this doc used to define is retired. The orchestrator now
+prints one of three report screens, filled from the record by `scripts/report-screen`, never
+written by eye:
+
+- **`report-screen state <intent_dir> [--changed "<text>"]`** - the mid-delivery report. One
+  intent's field table (Store, Status, Stage, Savepoint, Progress, Next, Insight) plus a
+  `Changed` row naming what caused the print, and its Steps table.
+- **`report-screen state --all <store_root>`** - the roster across every in-delivery intent,
+  most recently changed first, then one collapsed block (Stage, Next, Changed, first three
+  open steps) per intent.
+- **`report-screen delivered <intent_dir>`** - the post-delivery report, printed once at close:
+  Asked, Delivered (with a Proven-by column), Evidence, Needs you.
+- **`report-screen delay <intent_dir>`** - printed only on request ("why did X take so long"):
+  the delivery as a timeline plus the derived `Where the time went` line.
+
+## The five triggers for `state`
+
+Print `state` (one intent, or `--all` for the roster) on any of these; a checklist tick alone,
+an executor's intermediate commit, or an agent going idle is NOT one of them:
+
+| Trigger | Scope |
+|---|---|
+| A savepoint line lands (a stage boundary: Why, How, Exec started, outcome written, Done) | that intent |
+| A review verdict returns (plan review or post-execution review), naming what it changed | that intent |
+| A blocker or needs-input is logged | that intent |
+| A merge or a release lands | that intent |
+| The owner asks ("where are we", "state of X", "continue X") | all in delivery, or the one named |
+
+`delivered` prints exactly once, at Completion. `delay` prints only when the owner asks why a
+delivery took long.
+
+Every verb prints the same plain Markdown on every harness (owner ruling 2026-08-31); where a
+harness can paint it (Claude Code, through 316a's message-display hook), it substitutes a
+painted rendering of that same output, never a different one, and no skill or script branches
+on harness name to decide.
 
 ## Depth for small work
 
-For small work in auto mode the mid-flight briefings collapse to one. Only the How briefing fires, and
-it folds in what the What and Why briefings would have said: the work picked up and the approach
-chosen go into its State line. The Exec briefing folds into the final owner report at End. Larger
-work sends all four. The shape does not change: still State, then Risk, then Call, and the per-stage
-content above still says what each line covers. This is a depth cut, not a new report. A delivery
-still ends with `outcome.md` plus one owner report.
+For small work in auto mode, only the How-boundary `state` screen prints mid-flight (its
+`Changed` row names what the What and Why steps did, since there is no separate briefing per
+stage any more). Larger work prints `state` at every trigger in the table above. This is a
+depth cut, not a different report: the screen's shape never changes, only how often it fires.
+A delivery still ends with `outcome.md` plus one `delivered` screen.
 
 ## One report per audience
 
 A delivery produces exactly two artifacts: `outcome.md` (authored by `plastic-intent-ending`)
-and one EM-to-CTO owner report at the End stage. No stage or skill restates a delivery
-already written to `outcome.md`; point at it instead. Skills do not open with a banner that
-names the skill or restates the intent id and name the owner just typed. Announce only what
-the reader cannot already know: an error, a result, a choice with its reason, or a handoff.
+and one `delivered` screen at the End stage. No stage or skill restates a delivery already
+written to `outcome.md`; point at it instead. Skills do not open with a banner that names the
+skill or restates the intent id and name the owner just typed. Announce only what the reader
+cannot already know: an error, a result, a choice with its reason, or a handoff.
 
 ## Boundary vs intent 74
 
 Intent 74's report contract (`references/agent-report-contract.md`) is the INTERNAL,
 machine-checked handoff from a dispatched specialist back to the orchestrator: a structured
-envelope plus a per-role payload. This contract is the OUTWARD human briefing, orchestrator to
-user, in prose. Different direction, different audience, different form. The orchestrator
-CONSUMES the intent 74 report to WRITE the human briefing defined here. The two never merge.
+envelope plus a per-role payload. This contract is the OUTWARD screen shown to the owner.
+Different direction, different audience, different form. The orchestrator reads the intent 74
+report and reflects it into the record (savepoint, outcome.md) that `report-screen` then
+renders. The two never merge.
 
 ## Brevity: point, don't repeat
 
-Surface rules are owned by the `writing-style` skill. This contract does not restate them, in full
-or in summary. It defines the report's shape only: what to say, in what order, and when to stop.
-Apply the `writing-style` skill for the wording.
+Surface rules are owned by the `writing-style` skill. This contract does not restate them. Its
+job is naming which screen prints when, not the wording inside it - `report-screen` derives
+every cell from the record (D14), so there is no prose left to style here.
 
 ## Emission: guided vs auto
 
-In guided mode, the briefing lands at each stage boundary and the human acts on the Call line
-before the next stage starts.
+In guided mode, `state` prints at each stage boundary and the human decides before the next
+stage starts.
 
-In auto mode, for larger work the orchestrator still emits the briefing at each boundary, as a
-running EM-to-CTO account. For small work only the How briefing fires; see `## Depth for small work` above for what it
-folds in. The Call line becomes the go-ahead the orchestrator takes itself and moves on, except at
-the existing hard stops (destructive action without a safe alternative, project-path confirm).
+In auto mode, `state` prints at every trigger for larger work; for small work only the How
+boundary prints (see `## Depth for small work` above). The orchestrator takes the go-ahead
+itself and moves on, except at the existing hard stops (destructive action without a safe
+alternative, project-path confirm).

package/skills/conventions/references/locks-and-worktrees.md

@@ -103,3 +103,15 @@ what gets written down.
 | Exec | code on the intent branch, checklist checked off | heartbeat; code edits confined to the provisioned worktree; delegates write under the owner's lock | checklist boxes; savepoint milestones; the day-ledger line promotes when a project file lands |
 | End (done) | mandatory `outcome.md` (`disposition: delivered\|abandoned`), INDEX moves to Completed or Abandoned | ordered End tail: verify, merge and remove worktrees, disarm clears `delivery.lock`, then the pointer is purge-eligible, and the QMD reindex runs LAST (after purge); `end-intent` backfills a placeholder `outcome.md` from the record and its structure check reports (never refuses) | savepoint `Done delivered` (or `abandoned`); takeover audits, if any, remain in savepoint.md |
 | Maintenance (Future, Terminal, or Active-with-a-stale-or-no-lock) | `revisions.md` move-and-record entries | detects (never acquires) `delivery.lock`; defers and reports while the target's lock is FRESH (`Lock.fresh?`); a stale or absent lock is not-active, maintenance proceeds | append-only, rule-tagged `revisions.md` entry written in the same operation as the change, or the change is refused; lands via a fresh branch off store main merged back as one closed op, never `git add -A` |
+
+## The write guard is not residue
+
+`<type>.write.lock` (usually `delivery.write.lock`) is a deliberate sibling
+inode used only for `flock`: no owner, no timestamp, no content, and it is
+NEVER unlinked - deleting it while a writer holds the flock hands the next
+writer a fresh inode at the same path, so two writers hold "the" guard at
+once (see `scripts/lib/lock.rb`, the write-guard comment). A zero-byte
+`*.write.lock` in a completed intent directory is by design; no cleaner may
+sweep it, and it is already inside the store's `*.lock` gitignore rule.
+(Intent 317a, A2: a review misread it as stale residue and nearly shipped
+the sweep.)