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

package/scripts/runner

@@ -0,0 +1,392 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "lib/savepoint"
+require_relative "lib/ready_set"
+require_relative "lib/runner_core"
+
+# runner - the one executable over the graph-ready loop's declared node graph
+# (intent 340, G7, n1). A subcommand table: the public verbs (step, status,
+# answer) are the only ones the skill body ever names; the internal verbs
+# (ready, sweep, rewind) route and work so `step` can compose them and so
+# each can be tested alone, but stay out of the usage text (327 spec).
+#
+# `step`, `sweep`, `answer` and `rewind` route to modules later nodes
+# deliver (RunnerDispatch and RunnerAbsorb for `step`; RunnerSweep,
+# RunnerAnswer, RunnerRewind for the rest). Each is required LAZILY, inside
+# its own verb branch: a verb whose module has not landed yet reports
+# plainly and exits nonzero, and every other verb - most importantly
+# `status`, which an operator polls constantly across all five of this
+# intent's dispatches - keeps working.
+#
+# Usage:
+#   runner <step|status|answer> <intent_dir> [--node ID] [--answer TEXT]
+#
+# Exit codes (matching the family scripts/node-transition and
+# scripts/ready-set already use):
+#   0 - success
+#   1 - the verb ran but reports failure (an invalid graph for `ready`)
+#   2 - usage: unknown verb, or not an intent directory
+#   3 - a routed verb's module has not been delivered yet
+module Runner
+  module_function
+
+  PUBLIC_VERBS = %w[step status answer].freeze
+  INTERNAL_VERBS = %w[ready sweep rewind].freeze
+  VERBS = (PUBLIC_VERBS + INTERNAL_VERBS).freeze
+
+  # verb -> [[ModuleName, lib_file], ...], required lazily inside the verb's
+  # own branch (row 1.6). `step` composes two modules (dispatching new work,
+  # then absorbing what a sub-agent reported back); every other routed verb
+  # names exactly one.
+  LAZY_MODULES = {
+    "step" => [["RunnerSweep", "runner_sweep"], ["RunnerAbsorb", "runner_absorb"],
+               ["RunnerDispatch", "runner_dispatch"]],
+    "sweep" => [["RunnerSweep", "runner_sweep"]],
+    "answer" => [["RunnerAnswer", "runner_answer"]],
+    "rewind" => [["RunnerRewind", "runner_rewind"]],
+  }.freeze
+
+  def usage
+    warn "Usage: runner <#{PUBLIC_VERBS.join('|')}> <intent_dir> [--node ID] [--answer TEXT]"
+  end
+
+  def intent_directory?(dir)
+    dir && File.directory?(dir) && File.exist?(Savepoint.intent_file(dir))
+  end
+
+  def opt(args, name)
+    (i = args.index(name)) && args[i + 1]
+  end
+
+  # opt_all(args, name) -> every value given for a repeated flag, in the order
+  # they appear, or [] when the flag never occurs (intent 340, G7, n8, row
+  # 8.1-8.3). `run_step` needs this, not `opt`, for `--return`: one step may
+  # carry more than one `--return NODE=PATH` pair (one per node the session
+  # is reporting back on), and `opt`'s single-value semantics would silently
+  # keep only the first, absorbing one node while stranding the other's
+  # lease until it expires.
+  def opt_all(args, name)
+    args.each_index.select { |i| args[i] == name }.map { |i| args[i + 1] }.compact
+  end
+
+  # KNOWN_FLAGS (minor 2): the exact flag vocabulary each verb accepts. A
+  # flag not in a verb's own list is refused rather than silently ignored -
+  # a mistyped `--session` used to vanish with no effect and the runner
+  # simply acted as whichever session `CLAUDE_CODE_SESSION_ID` names.
+  KNOWN_FLAGS = {
+    "step" => %w[--return --allow-core-drift],
+    "answer" => %w[--node --answer],
+    "rewind" => %w[--node --confirm],
+  }.freeze
+
+  # unrecognized_flag(verb, args) -> the first token in `args` that looks
+  # like a flag (`--...`) and is not in `verb`'s own KNOWN_FLAGS, or nil. A
+  # verb absent from KNOWN_FLAGS (status, ready, sweep) accepts none.
+  def unrecognized_flag(verb, args)
+    allowed = KNOWN_FLAGS.fetch(verb, [])
+    args.find { |a| a.is_a?(String) && a.start_with?("--") && !allowed.include?(a) }
+  end
+
+  def main(argv)
+    args = argv.dup
+    verb = args.shift
+
+    unless VERBS.include?(verb)
+      warn "runner: unknown verb #{verb.inspect}"
+      usage
+      exit 2
+    end
+
+    intent_dir_arg = args.shift
+    unless intent_directory?(intent_dir_arg && File.expand_path(intent_dir_arg))
+      warn "runner: #{intent_dir_arg.inspect} is not an intent directory"
+      usage
+      exit 2
+    end
+    intent_dir = File.expand_path(intent_dir_arg)
+
+    bad_flag = unrecognized_flag(verb, args)
+    if bad_flag
+      warn "runner: unknown flag #{bad_flag.inspect} for #{verb}"
+      usage
+      exit 2
+    end
+
+    case verb
+    when "status"
+      run_status(intent_dir)
+    when "ready"
+      run_ready(intent_dir)
+    else
+      run_lazy(verb, intent_dir, args)
+    end
+  end
+
+  def run_status(intent_dir)
+    context = RunnerCore.context(intent_dir: intent_dir, env: ENV["CLAUDE_CODE_SESSION_ID"])
+    rows = RunnerCore.status(context)
+
+    if rows.empty?
+      puts "No declared nodes."
+    else
+      rows.each do |id, view|
+        puts "#{id}  kind=#{view[:kind]}  state=#{view[:state]}  ready=#{view[:ready]}"
+        last = view[:last_transition]
+        puts "  last: #{last[:raw]}" if last
+      end
+    end
+
+    complete = RunnerCore.complete?(context)
+    puts
+    puts complete ? "complete" : "stalled"
+    unless complete
+      rows.each do |id, view|
+        next if ReadySet::TERMINAL_STATES.include?(view[:state])
+
+        view[:blockers].each { |b| puts "#{id} blocked: #{b}" }
+      end
+    end
+
+    exit 0
+  end
+
+  def run_ready(intent_dir)
+    analysis = ReadySet.analyze(intent_dir)
+    unless analysis[:ok]
+      warn "runner: #{analysis[:errors].join('; ')}"
+      exit 1
+    end
+
+    if analysis[:ranked_ready].empty?
+      puts "Ready: (none)"
+    else
+      puts "Ready: #{analysis[:ranked_ready].map { |r| r[:id] }.join(', ')}"
+    end
+    exit 0
+  end
+
+  # Requires this verb's module(s) lazily, then hands off. Nothing in n1
+  # delivers runner_dispatch.rb, runner_absorb.rb, runner_sweep.rb,
+  # runner_answer.rb, or runner_rewind.rb, so every LAZY_MODULES require
+  # raises LoadError today and every routed verb reports "not yet
+  # delivered" - the only thing this node needs to prove (row 1.6). Once a
+  # later node ships its file, the require succeeds and falls through to
+  # dispatch_lazy, which that node replaces with the real call.
+  def run_lazy(verb, intent_dir, args)
+    # The require target below is a runtime value, never an inline quoted
+    # literal, so it falls outside test/install_packaging_test.rb's
+    # require-closure guard on purpose: every file LAZY_MODULES names is a
+    # genuine later-node deliverable, none of which core_files should track
+    # until that node actually lands it.
+    LAZY_MODULES.fetch(verb, []).each { |(_name, file)| require_relative(File.join("lib", file)) }
+  rescue LoadError
+    warn "runner: #{verb} is not yet delivered (its module has not landed)"
+    exit 3
+  else
+    dispatch_lazy(verb, intent_dir, args)
+  end
+
+  def dispatch_lazy(verb, intent_dir, args)
+    case verb
+    when "step"
+      run_step(intent_dir, args)
+    when "sweep"
+      run_sweep(intent_dir, args)
+    when "answer"
+      run_answer(intent_dir, args)
+    when "rewind"
+      run_rewind(intent_dir, args)
+    else
+      warn "runner: #{verb}'s module loaded but no dispatcher is wired up yet"
+      exit 3
+    end
+  end
+
+  # run_sweep (intent 340, G7, n8): the standalone `sweep` verb, unreachable
+  # from the CLI until this node - `dispatch_lazy` had no `when "sweep"` arm
+  # even though `RunnerSweep.run` (n2) is a complete, documented standalone
+  # entry point, exactly the shape a bare `runner sweep` call needs (abort
+  # check, THEN the lease heartbeat, THEN reclaim - RunnerSweep's own fixed
+  # order). `step` never calls this method: it composes `abort_if_merging`
+  # and `reclaim` itself, interleaved around absorb.
+  def run_sweep(intent_dir, args)
+    context = RunnerCore.context(intent_dir: intent_dir, env: ENV["CLAUDE_CODE_SESSION_ID"])
+    result = RunnerSweep.run(context)
+
+    unless result[:ok]
+      warn "runner: #{result[:error]}"
+      warn "runner: run `#{result[:recovery_command]}` before the next sweep can run" if result[:recovery_command]
+      exit 1
+    end
+
+    result[:reclaimed].each { |r| puts "reclaimed #{r[:node]} (holder=#{r[:holder]})" }
+    result[:extended].each { |e| puts "extended #{e[:node]} (head=#{e[:head]})" }
+    puts "nothing to sweep" if result[:reclaimed].empty? && result[:extended].empty?
+    exit 0
+  end
+
+  # run_answer (intent 340, G7, n6): closes a decision node or unparks a
+  # work node the runner parked at `needs_decision` (327 D22, C26), then
+  # prints what became ready so the owner knows the loop can continue.
+  def run_answer(intent_dir, args)
+    node = opt(args, "--node")
+    text = opt(args, "--answer")
+
+    unless node
+      warn "runner: answer requires --node ID"
+      exit 2
+    end
+
+    context = RunnerCore.context(intent_dir: intent_dir, env: ENV["CLAUDE_CODE_SESSION_ID"])
+    result = RunnerAnswer.answer(context, node: node, text: text.to_s)
+
+    unless result[:ok]
+      warn "runner: answer refused (#{result[:reason]})"
+      exit 1
+    end
+
+    puts "answered #{node}"
+    puts "respun to #{result[:respun_to]}" if result[:respun_to]
+    puts "newly ready: #{result[:newly_ready].join(', ')}" if result[:newly_ready].any?
+    exit 0
+  end
+
+  # run_rewind (intent 340, G7, n6): confirm-gated reset of the intent
+  # branch to a node's own recorded commit, superseding every downstream
+  # node and respinning the rewound node itself (327 D15's rewind clause).
+  def run_rewind(intent_dir, args)
+    node = opt(args, "--node")
+    confirm = args.include?("--confirm")
+
+    unless node
+      warn "runner: rewind requires --node ID"
+      exit 2
+    end
+
+    context = RunnerCore.context(intent_dir: intent_dir, env: ENV["CLAUDE_CODE_SESSION_ID"])
+    result = RunnerRewind.rewind(context, node: node, confirm: confirm)
+
+    unless result[:ok]
+      warn "runner: rewind refused (#{result[:reason]})"
+      exit 1
+    end
+
+    puts "reset #{node} to #{result[:reset_to]}"
+    puts "superseded: #{result[:superseded].join(', ')}" if result[:superseded].any?
+    puts "respun to #{result[:respun_to]}"
+    exit 0
+  end
+
+  # run_step (intent 340, G7, n5): one turn of the loop, in the fixed order
+  # 327 D14 and RunnerSweep's own docstring name - abort on a stuck merge,
+  # the delivery-lease heartbeat, absorb every `--return NODE=PATH` this call
+  # carries, THEN reclaim (so a node this very call just absorbed is never
+  # reclaimed out from under its own return, matrix row 2.19/2.20) - and only
+  # then dispatch whatever is left ready. Never spawns an agent (327 D42):
+  # the session makes every subagent call from the plan this prints.
+  def run_step(intent_dir, args)
+    context = RunnerCore.context(intent_dir: intent_dir, env: ENV["CLAUDE_CODE_SESSION_ID"])
+
+    # v1 minor 3/row 11.18: RunnerSweep.abort_if_merging already prints the
+    # whole sentence itself (its own error PLUS the recovery command) - this
+    # used to print both halves again, so the operator read the same merge
+    # warning twice for one refusal.
+    abort_result = RunnerSweep.abort_if_merging(context)
+    exit 1 unless abort_result[:ok]
+
+    Lock.heartbeat(intent_dir, session: context.session) unless context.session.to_s.strip.empty?
+
+    # B4: this is the runner's ACTUAL lock check now - the absorb loop below
+    # writes node transitions, and RunnerDispatch's own check (row 5.31/5.32)
+    # runs too late to stop that: a session holding no lock would otherwise
+    # have every `--return` it carries written anyway, attributed to
+    # whichever session's holder= happens to be on the node's `running`
+    # line. RunnerDispatch keeps its own check too, as defence in depth for
+    # a caller that reaches it some other way.
+    unless context.session
+      warn "runner: step refused (lock_not_held)"
+      warn RunnerDispatch.rearm_command(intent_dir)
+      exit 1
+    end
+
+    # M3/row 10.1: `--allow-core-drift` (D11) - the one escape hatch letting
+    # Plastic's own repository, which legitimately drifts from the installed
+    # manifest, dogfood its own runner. Threaded straight into the absorb,
+    # never defaulted true.
+    allow_core_drift = args.include?("--allow-core-drift")
+
+    returns = {}
+    opt_all(args, "--return").each do |pair|
+      node, path = pair.to_s.split("=", 2)
+      if node.to_s.empty? || path.to_s.empty?
+        warn "runner: malformed --return #{pair.inspect}, expected NODE=PATH"
+        exit 2
+      end
+      returns[node] = path
+    end
+
+    returns.each do |node, path|
+      absorbed = RunnerAbsorb.absorb(context, node: node, return_path: path, allow_core_drift: allow_core_drift)
+      puts "absorbed #{node}: #{absorbed[:state]}"
+      # M4/row 10.3: a refused proposal is surfaced here, not left to a
+      # savepoint comment the operator never sees - the exact reason the
+      # proposer's next attempt otherwise proposes the same thing again.
+      proposal = absorbed[:proposal]
+      puts "  proposal refused: #{Array(proposal[:errors]).join('; ')}" if proposal && !proposal[:ok]
+    end
+
+    swept = RunnerSweep.reclaim(context, skip: returns.keys)
+    swept[:reclaimed].each { |r| puts "reclaimed #{r[:node]} (holder=#{r[:holder]})" }
+    swept[:extended].each { |e| puts "extended #{e[:node]} (head=#{e[:head]})" }
+
+    # M5/row 10.4: NodeWorktree.reap runs once per step, right after the
+    # reclaim pass - D26's reaper, unreachable from anywhere until now.
+    reaped = NodeWorktree.reap(context)
+    reaped[:removed].each { |r| puts "reaped #{r[:node]} worktree" }
+
+    result = RunnerDispatch.dispatch(context)
+    unless result[:ok]
+      warn "runner: step refused (#{result[:reason]}): #{Array(result[:errors]).join('; ')}"
+      warn result[:rearm_command] if result[:rearm_command]
+      exit 1
+    end
+
+    case result[:status]
+    when "dispatched"
+      puts result[:plan]
+    when "queued"
+      puts "queued (concurrency ceiling reached)"
+    when "complete"
+      puts "complete"
+    when "needs_decision"
+      # printed below, alongside a dispatch plan when the same step also
+      # dispatched (M11/row 10.14) - `result[:stop]` is set whenever
+      # status is needs_decision.
+    else
+      puts "stalled"
+      result[:blockers].each { |b| puts "blocked: #{b}" }
+    end
+
+    # M11/row 10.14: a `needs_decision` stop must print even when THIS SAME
+    # step also dispatched other nodes ahead of the decision node in ranked
+    # order - `result[:status]` reads "dispatched" in that case (dispatched
+    # takes priority in RunnerDispatch's own report), which used to swallow
+    # the stop and its `runner answer` command entirely.
+    if result[:stop]
+      stop = result[:stop]
+      puts "needs_decision: #{stop[:node]} - #{stop[:question]}"
+      puts stop[:answer_command]
+    end
+
+    result[:parked].each do |p|
+      puts "parked #{p[:node]} (#{p[:reason]}): #{p[:question]}"
+      puts p[:answer_command]
+    end
+
+    exit 0
+  end
+end
+
+Runner.main(ARGV) if $PROGRAM_NAME == __FILE__

package/scripts/savepoint-note

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# savepoint-note - the writer CLI for three savepoint kinds: Review (one line per
+# plan-review or post-execution-review verdict) and Commit (one line per commit landing
+# during Exec), both from intent 317, D17; and Report (one line per report screen printed,
+# intent 331f). None has an automatic seam (session-commit writes the day ledger, not the
+# intent ledger; the executor's own commits are plain git; a printed screen is a skill's own
+# reply, not a file write), so this is an explicit thin wrapper on
+# Savepoint.append_review_savepoint / append_commit_savepoint / append_report_savepoint.
+#
+# Usage:
+#   savepoint-note <intent_dir> --kind Review|Commit|Report --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|Report --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 Report].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)
+when "Report" then Savepoint.append_report_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/scripts/validate-work-graph

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# validate-work-graph - deterministic CLI over WorkGraphValidator (intent 334, n4).
+#
+# Checks whether one intent directory's graph.md and nodes/ form a valid work
+# graph: needs targets resolve, node files reconcile with the declared graph,
+# per-kind body sections are present, and (above the trivial bar) a verify
+# node gates two or more work nodes with a failure-mode matrix per work node.
+# Modelled on scripts/validate-intent: errors to stderr, same exit-code shape.
+#
+# Usage:
+#   validate-work-graph <intent_dir>
+#
+# Exit codes: 0 (valid), 1 (invalid or unreadable; report on stderr),
+# 2 (usage - no argument given).
+
+require_relative "lib/work_graph_validator"
+
+intent_dir = ARGV.find { |a| !a.start_with?("--") }
+
+if intent_dir.nil?
+  warn "usage: validate-work-graph <intent_dir>"
+  exit 2
+end
+
+dir = File.expand_path(intent_dir)
+result = WorkGraphValidator.validate(dir)
+
+if result[:ok]
+  puts "OK: #{dir}"
+  exit 0
+end
+
+warn "INVALID: #{dir}"
+result[:missing].each { |m| warn "missing: #{m}" }
+result[:errors].each { |e| warn e }
+exit 1

package/scripts/verify-intent

@@ -15,7 +15,8 @@
 # other flags exist.
 #
 # Checks, all run every invocation (the fourth only when --suite is given):
-#   1. doctor    - Doctor#run_intent_check(id, store: scope), fail-open on a crash
+#   1. doctor    - Doctor#run_intent_check(id, store: scope), fail-open on a crash; the doctor
+#                  scan includes the intent_ticks_lag warning (intent 329)
 #   2. em-dash   - added lines only of `git diff <base>...HEAD`, never the whole tree
 #   3. diffstat  - `git diff --stat <base>...HEAD`, never a failure on its own
 #   4. suite     - the supplied --suite command, run with RUBYOPT cleared

package/skills/auto/SKILL.md

@@ -67,8 +67,9 @@ Replace `<STORE>` (`~/.plastic/projects/<slug>/store` or `~/.plastic/store`) and
 nonblank `CLAUDE_CODE_SESSION_ID` as Claude, otherwise passes no identity and the verb keys the
 lock by a derived session key. Never guess identity from an absent runtime variable; an
 unknown harness or thread stays unknown. Exit 1 means the lock is held, stale, excluded, or
-corrupt; the message names the `plastic-doctor` verb that resolves it. Do not proceed as the
-owner after an exit 1.
+corrupt - or `inline_refused`: a conversation session may not arm an intent at all (owner rule
+2026-08-31); dispatch the delivery team instead. `--allow-inline` exists only for an explicit
+owner override. Do not proceed as the owner after an exit 1.
 
 Read `../plastic-conventions/references/locks-and-worktrees.md` for what the lock and the
 worktree mean and the station table behind them. Code edits happen only inside the worktree.
@@ -168,6 +169,7 @@ ledger is missing (then rebuild it with `Savepoint.rebuild_savepoint`).
 | `How  plan.md created` / `How  checklist.md created` / `Exec  started` | Exec (verify plan, matrix, checklist) |
 | `Exec  outcome.md created` | Exec done; complete the intent |
 | `Done  delivered|abandoned` | Terminal; do not resume |
+| A node or `Intent` transition line (`n1  running ...`, `Intent  needs_decision ...`) | Exec; a graph delivery is in progress - drive it through `scripts/runner`'s three public verbs, `step` (one turn of the dispatch loop), `status` (renders ledger state, safe to poll constantly), and `answer` (closes a `needs_decision` node) - read node status through `NodeLedger.status` before dispatching anything, never re-derive it by eye |
 
 Filesystem fallback, in order: `checklist.md` with items checked means resume Exec from the
 first unchecked item; `plan.md` plus `checklist.md` means enter Exec; `spec.md` alone means
@@ -183,9 +185,7 @@ Announce which stage you are entering and why.
 3. Decide: pick the best option per gap, record it in `## Context > ### Decisions` with the
    rationale, and log it in `## Insights` with the `(autonomous)` marker through
    `scripts/insight-append`.
-4. Write `spec.md`.
-
-Then How.
+4. Write `spec.md`. Then How.
 
 ## How (the lead), then the plan review
 
@@ -200,9 +200,9 @@ 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 plan <intent_dir>` as the first characters of
+   the reply, nothing before it, no fence, before dispatching the executor (see
+   `references/human-report-contract.md` for the full binding table). It informs; it does not wait.
 
 Then Exec.
 
@@ -214,7 +214,7 @@ Then Exec.
    then builds, then drives the full suite green.
 2. Read its return by code: DONE or DONE_WITH_CONCERNS proceeds; NEEDS_CONTEXT re-dispatches
    with the missing context; BLOCKED stops under the error procedure.
-3. Tick the checklist as items land (the executor does this; verify it).
+3. Tick the checklist as items land (the executor does this); verify tick-versus-diff against the diff. A mismatch is a review finding, not a lead cleanup.
 
 ## Review by risk (boot 3, only when a rule fires)
 
@@ -251,8 +251,9 @@ 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`.
+1. This is the merge gate: verify every checklist item is checked, verify tick-versus-diff against the diff, and confirm the suite is green once on the branch.
+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,
@@ -268,10 +269,16 @@ Read `../plastic-conventions/references/completion-and-done.md` for what "intent
      --session "$CLAUDE_CODE_SESSION_ID" \
      --index-note "<what shipped>; <suite result>"
    ```
-   Exit 4 means a live foreign session holds the lock; 5 means the worktree is dirty (commit
-   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.
+   Exit 4: a live foreign session holds the lock. 5: the worktree is dirty (commit first, or
+   pass `--discard-worktree-changes` deliberately). 3: the lock survived the disarm
+   (`/plastic-doctor check the lock status`). 6: 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/331f), and
+   `report-screen state` at each of the five triggers in `references/human-report-contract.md`
+   (a review verdict, a blocker, a merge/release, or an owner status ask; a mid-batch ask
+   instead runs `report-screen session <tier_root> --session "$CLAUDE_CODE_SESSION_ID"`, intent
+   330). Print each as the first characters of the reply: nothing before it, no fence, or the
+   hook cannot paint it.
 
 ## Error Handling
 
@@ -284,8 +291,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