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

package/scripts/lib/session_git.rb

@@ -207,11 +207,37 @@ module SessionGit
 
   # --- commit message ------------------------------------------------------------
 
-  # The first line of `summary`, truncated to MAX_SUBJECT_LENGTH characters,
-  # with no trailer (spec D5).
+  # The first line of `summary`, cut at the last word boundary at or before
+  # MAX_SUBJECT_LENGTH characters, falling back to the hard slice when no
+  # boundary exists at or before the limit (spec D6, amends spec 300 D5's
+  # unconditional `first_line[0, MAX_SUBJECT_LENGTH]`, which cut mid-word).
+  # A subject at or under the limit is returned unchanged. Post-execution
+  # review item 7: when the character immediately after the 72-char prefix
+  # is ITSELF a space, the prefix already ends exactly on a word boundary and
+  # needs no trimming at all -- checked before consulting `rindex`, because
+  # an earlier internal space inside the 72-char prefix would otherwise make
+  # `rindex` walk back past a whole trailing word that fit perfectly.
   def subject_for(summary)
     first_line = summary.to_s.split(/\r?\n/, 2).first.to_s.strip
-    first_line[0, MAX_SUBJECT_LENGTH]
+    return first_line if first_line.length <= MAX_SUBJECT_LENGTH
+
+    cut = first_line[0, MAX_SUBJECT_LENGTH]
+    return cut if first_line[MAX_SUBJECT_LENGTH] == " "
+
+    boundary = cut.rindex(" ")
+    boundary ? cut[0, boundary] : cut
+  end
+
+  # The commit body for `summary`/`subject` (spec D6): the full summary when
+  # `subject` is a cut-down copy of it, nil when the subject already carries
+  # the summary whole (no redundant body on a short, single-line summary).
+  # Post-execution review item 4: compares the STRIPPED raw summary, not the
+  # raw summary verbatim -- a summary with only trailing/leading whitespace
+  # around an otherwise-identical subject must not repeat the same sentence
+  # twice as a redundant body.
+  def body_for(summary, subject)
+    raw = summary.to_s
+    raw.strip == subject ? nil : raw
   end
 
   # --- git primitives (all use -C, never cwd) -------------------------------------
@@ -273,9 +299,11 @@ module SessionGit
     parts.each_cons(2).any? { |a, b| a == ".claude" && b == "worktrees" }
   end
 
-  def stage_and_commit(dir, subject, runner:)
+  def stage_and_commit(dir, subject, runner:, body: nil)
     runner.run("-C", dir, "add", "-A")
-    runner.run("-C", dir, "commit", "-m", subject)
+    args = ["-C", dir, "commit", "-m", subject]
+    args += ["-m", body] if body
+    runner.run(*args)
   end
 
   def short_sha(dir, runner:)
@@ -310,14 +338,16 @@ module SessionGit
 
     flow, flow_notes = load_flow(cwd: cwd, repo: repo, plastic_home: plastic_home, runner: runner)
     subject = subject_for(summary)
+    body = body_for(summary, subject)
 
     result =
       if flow["mode"] == "pull_request"
-        commit_pull_request(repo: repo, subject: subject, day: day, session: session,
+        commit_pull_request(repo: repo, subject: subject, body: body, day: day, session: session,
                              store: effective_store, flow: flow, branch_now: branch_now,
                              runner: runner, gh_runner: gh_runner)
       else
-        commit_direct(repo: repo, subject: subject, day: day, flow: flow, branch_now: branch_now, runner: runner)
+        commit_direct(repo: repo, subject: subject, body: body, day: day, flow: flow, branch_now: branch_now,
+                       runner: runner)
       end
 
     return result if flow_notes.empty?
@@ -331,7 +361,7 @@ module SessionGit
 
   # --- direct mode (spec D3) --------------------------------------------------------
 
-  def commit_direct(repo:, subject:, day:, flow:, branch_now:, runner:)
+  def commit_direct(repo:, subject:, day:, flow:, branch_now:, runner:, body: nil)
     return note("nothing to commit") unless dirty?(repo, runner: runner)
     return note("summary is empty after truncation: no commit") if blank?(subject)
 
@@ -351,10 +381,10 @@ module SessionGit
     end
 
     if branch_now == base || branch_now == session_branch
-      commit_on_session_branch(repo: repo, subject: subject, base: base,
+      commit_on_session_branch(repo: repo, subject: subject, base: base, body: body,
                                 session_branch: session_branch, branch_now: branch_now, runner: runner)
     else
-      commit_on_other_branch(repo: repo, subject: subject, branch_now: branch_now, runner: runner)
+      commit_on_other_branch(repo: repo, subject: subject, body: body, branch_now: branch_now, runner: runner)
     end
   end
 
@@ -367,7 +397,7 @@ module SessionGit
   # session branch. `current_branch` is re-read after the switch and used
   # for the commit message instead of trusting the branch this method
   # intended to reach.
-  def commit_on_session_branch(repo:, subject:, base:, session_branch:, branch_now:, runner:)
+  def commit_on_session_branch(repo:, subject:, base:, session_branch:, branch_now:, runner:, body: nil)
     unless branch_exists?(repo, session_branch, runner: runner)
       create = runner.run("-C", repo, "branch", session_branch, base.to_s)
       return note("could not create session branch #{session_branch}: #{diagnose(create)}") unless create.success?
@@ -383,11 +413,12 @@ module SessionGit
       return note("expected to be on #{session_branch} but the checkout is on #{actual_branch.inspect}")
     end
 
-    commit_and_push(dir: repo, push_dir: repo, subject: subject, from: actual_branch, base: base, runner: runner)
+    commit_and_push(dir: repo, push_dir: repo, subject: subject, body: body, from: actual_branch, base: base,
+                     runner: runner)
   end
 
-  def commit_on_other_branch(repo:, subject:, branch_now:, runner:)
-    res = stage_and_commit(repo, subject, runner: runner)
+  def commit_on_other_branch(repo:, subject:, branch_now:, runner:, body: nil)
+    res = stage_and_commit(repo, subject, runner: runner, body: body)
     return note("commit rejected by commit-msg hook: #{diagnose(res)}") unless res.success?
 
     sha = short_sha(repo, runner: runner)
@@ -398,8 +429,8 @@ module SessionGit
   # shared tail. A non-fast-forward push (spec D3, "base moved ahead
   # independently") stays a Note: the commit itself already landed on the
   # session branch.
-  def commit_and_push(dir:, push_dir:, subject:, from:, base:, runner:)
-    res = stage_and_commit(dir, subject, runner: runner)
+  def commit_and_push(dir:, push_dir:, subject:, from:, base:, runner:, body: nil)
+    res = stage_and_commit(dir, subject, runner: runner, body: body)
     return note("commit rejected by commit-msg hook: #{diagnose(res)}") unless res.success?
 
     sha = short_sha(dir, runner: runner)
@@ -414,7 +445,7 @@ module SessionGit
 
   # --- pull request mode (spec D4) ------------------------------------------------
 
-  def commit_pull_request(repo:, subject:, day:, session:, store:, flow:, branch_now:, runner:, gh_runner:)
+  def commit_pull_request(repo:, subject:, day:, session:, store:, flow:, branch_now:, runner:, gh_runner:, body: nil)
     return note("nothing to commit") unless dirty?(repo, runner: runner)
     return note("summary is empty after truncation: no commit") if blank?(subject)
 
@@ -439,7 +470,7 @@ module SessionGit
       return note("could not check out branch #{branch}: #{diagnose(switch)}") unless switch.success?
     end
 
-    res = stage_and_commit(repo, subject, runner: runner)
+    res = stage_and_commit(repo, subject, runner: runner, body: body)
     outcome =
       if res.success?
         pull_request_outcome(repo: repo, subject: subject, branch: branch, base: base, gh_runner: gh_runner, runner: runner)

package/scripts/lib/session_ledger.rb

@@ -29,6 +29,10 @@ module SessionLedger
 
   SESSIONS_DIR = ".sessions"
   TMP_DIR = ".tmp"
+  # Named here, not in a CLI, so a caller can reference the key without the
+  # literal harness-branded env var name appearing in its own source (a few
+  # scripts are guarded against naming a harness at all).
+  SESSION_ID_ENV_KEY = "CLAUDE_CODE_SESSION_ID"
   DAY_ID = /\A\d{8}\z/
   EVENTS = %w[Item Done Note]
   STATES = { pending: "~", open: " ", done: "x", moved: ">", dropped: "-", promoted: "^" }.freeze
@@ -186,6 +190,130 @@ module SessionLedger
     "#{collapsed[0, 197]}..."
   end
 
+  # --- capture_worthy? (spec D2, D7; supersedes 298 D2(c)) -------------------
+
+  # One complete top-level harness envelope tag block: "<name ...>...</name>".
+  # Non-greedy (.*?) so sibling blocks are each matched on their own rather
+  # than one match spanning from the first block's opening tag all the way to
+  # the LAST block's closing tag (post-execution review item 3: an envelope
+  # on both sides of real work, "<system-reminder>...</system-reminder>\nfix
+  # the parser\n<task-notification>...</task-notification>", must not be
+  # read as one giant envelope swallowing the work in the middle).
+  ENVELOPE_BLOCK_RE = /<([A-Za-z][\w-]*)(?:\s[^>]*)?>.*?<\/\1>/m
+  private_constant :ENVELOPE_BLOCK_RE
+
+  # The whole prompt, case- and whitespace-insensitively, and nothing else
+  # (rule 3, D2): a trigger word inside a longer real instruction ("continue
+  # the dashboard fix and then release") must not match this.
+  BARE_TRIGGERS = %w[continue auto].freeze
+  private_constant :BARE_TRIGGERS
+
+  # Words whose presence marks a prompt as actionable work (rule 4's escape
+  # hatch, D2's accept bias). Deliberately excludes common nouns that also
+  # read as everyday verbs in casual remarks (e.g. "release", "ship", "plan"):
+  # including them would make ordinary conversation about a past release or
+  # plan look like a work request. Matched with an optional inflection suffix
+  # (post-execution review BLOCKER): the bare stems alone missed "fixed",
+  # "updated", "added", "reviewed", "implemented" -- exactly the past-tense
+  # and -ing forms real work summaries use.
+  WORK_MARKER_WORDS = %w[
+    fix add remove delete update upgrade implement write build create refactor
+    debug investigate review test deploy commit merge revert rename configure
+    install migrate document generate draft resolve help need want make change
+    setup
+  ].freeze
+  private_constant :WORK_MARKER_WORDS
+
+  WORK_MARKER_PHRASES = [
+    "can you", "could you", "would you", "let's", "let us", "set up", "look into", "figure out",
+  ].freeze
+  private_constant :WORK_MARKER_PHRASES
+
+  WORK_MARKER_RE = /\b(?:#{WORK_MARKER_WORDS.join("|")})(?:s|d|ed|ing)?\b/i
+  private_constant :WORK_MARKER_RE
+
+  # A first word that reads as an interrogative opener, checked case-
+  # insensitively against the prompt's first whitespace-separated token.
+  # Post-execution review BLOCKER: trimmed from the original, wider list
+  # (which also carried "how", "when", "where", "was", "were", "do", "did",
+  # "will", "shall", "should") down to words that open a genuine QUESTION at
+  # least as often as an ordinary command or request. Measured against 43
+  # invented and 27 real day-ledger prompts: the dropped words open ordinary
+  # work requests ("do the release now...", "when you are done, tag the
+  # release...", "will you push that branch...", "should I bump the version
+  # files...") far more often than they open a bare question worth rejecting.
+  QUESTION_STARTERS = %w[
+    what why who whom whose which is are am does can could would
+  ].freeze
+  private_constant :QUESTION_STARTERS
+
+  # A narrow set of retrospective-remark shapes ("that release went smoother
+  # than the last one"): comparative or evaluative observations about how
+  # something already went. Deliberately narrow (D2's accept bias): a broad
+  # "any declarative sentence with no recognized verb" rule would also catch
+  # ordinary work summaries like "harness text wins the pending line", which
+  # must stay accepted.
+  REMARK_PATTERNS = [
+    /\bwent\s+\w+\s+than\b/i,
+    /\bwent\s+(?:well|badly|smoothly|great|poorly|terribly)\b/i,
+  ].freeze
+  private_constant :REMARK_PATTERNS
+
+  # True iff nothing but harness envelope tag block(s) -- and whitespace --
+  # remain once every complete top-level block is stripped out. A prompt
+  # that is one envelope alone, or several envelopes with no other content,
+  # matches; a prompt carrying real work anywhere outside an envelope (before,
+  # after, or between several of them) does not.
+  def whole_prompt_envelope?(stripped)
+    stripped.gsub(ENVELOPE_BLOCK_RE, "").strip.empty?
+  end
+
+  def bare_trigger?(stripped)
+    BARE_TRIGGERS.include?(stripped.downcase)
+  end
+
+  def work_marker?(text)
+    return true if WORK_MARKER_RE.match?(text)
+
+    downcased = text.downcase
+    WORK_MARKER_PHRASES.any? { |p| downcased.include?(p) }
+  end
+
+  def interrogative?(stripped)
+    return true if stripped.end_with?("?")
+
+    first_word = stripped.split(/\s+/).first.to_s.downcase.gsub(/[^a-z]/, "")
+    QUESTION_STARTERS.include?(first_word)
+  end
+
+  def bare_remark?(stripped)
+    REMARK_PATTERNS.any? { |re| re.match?(stripped) }
+  end
+
+  # Internal helpers only: #capture_worthy? is the sole public contract
+  # (post-execution review item 9).
+  private_class_method :whole_prompt_envelope?, :bare_trigger?, :work_marker?, :interrogative?, :bare_remark?
+
+  # Whether `prompt` earns a pending checklist line (spec D2). Bias is
+  # ACCEPT: this rejects only on four named rules -- the 10-char floor (on
+  # its own collapsed copy), a whole-prompt harness envelope, a bare
+  # continue/auto trigger, and an interrogative or bare-remark prompt
+  # carrying no work marker -- and accepts everything else, including a
+  # work-shaped question and an envelope followed by real work. Takes the
+  # RAW prompt (not the sanitized/truncated line text) so rule 2 sees the
+  # prompt's true first character and multi-line shape.
+  def capture_worthy?(prompt)
+    raw = prompt.to_s
+    return false if sanitize_summary(raw).length < 10
+
+    stripped = raw.strip
+    return false if whole_prompt_envelope?(stripped)
+    return false if bare_trigger?(stripped)
+    return false if !work_marker?(stripped) && (interrogative?(stripped) || bare_remark?(stripped))
+
+    true
+  end
+
   # One LF-terminated checklist line, byte exact per spec D5. The state
   # marker is fixed width across all three states, which is what lets a later
   # promote or tick be a one-byte write at a known offset.

package/scripts/lib/session_usage.rb

@@ -0,0 +1,190 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+# SessionUsage (intent 355, D10): reads the harness transcripts modified since
+# a cutoff, dedupes assistant records by message id (the harness logs one
+# record per content block), and reports per session the model, the calls in
+# the window, the boot and last context, the median step, the steps over 5k,
+# and the cache read. Context is input plus cache read plus cache write.
+# Broken records are counted and named, never averaged over. The transcripts
+# root and the rate-limit cache path are injected; nothing reads ENV.
+class SessionUsage
+  WINDOW = 5 * 3600
+  BIG_STEP = 5_000
+  LABEL_WIDTH = 70
+  NO_PROMPT = "(no prompt)"
+  SYNTHETIC_MODEL = "<synthetic>"
+  CONTEXT_FIELDS = %w[input_tokens cache_read_input_tokens cache_creation_input_tokens].freeze
+  TRANSCRIPT_GLOBS = [File.join("*", "*.jsonl"), File.join("*", "*", "subagents", "*.jsonl")].freeze
+  HEADERS = ["session", "model", "calls", "boot", "last", "median step", "big steps", "cache read", "broken", "prompt"].freeze
+
+  def initialize(transcripts_root:, rate_limits_path:, now: Time.now)
+    @transcripts_root = transcripts_root
+    @rate_limits_path = rate_limits_path
+    @now = now
+  end
+
+  def cutoff(since: nil)
+    return [since, "since"] if since
+
+    reset = reset_time
+    return [reset - WINDOW, "rate-limit reset"] if reset && reset > @now
+
+    [@now - WINDOW, "last 5 hours"]
+  end
+
+  def report(since: nil)
+    at, source = cutoff(since: since)
+    header = { "status" => "ok", "root" => @transcripts_root, "cutoff" => at.getutc.iso8601, "cutoff_source" => source }
+    return header.merge("status" => "unavailable") unless File.directory?(@transcripts_root)
+
+    broken = []
+    sessions = transcripts(at).filter_map { |path| summarize(path, at, broken) }
+    header.merge("sessions" => sessions.sort_by { |s| -s["cache_read"] }, "broken" => broken)
+  end
+
+  def self.render_text(report)
+    return "Session usage: unavailable (no transcripts directory at #{report['root']})\n" if report["status"] == "unavailable"
+
+    out = +"Session usage since #{report['cutoff']} (#{report['cutoff_source']})\n\n"
+    out << (report["sessions"].empty? ? "(no sessions)\n" : table(report["sessions"]))
+    return out if report["broken"].empty?
+
+    out << "\nBroken records (#{report['broken'].size}):\n"
+    report["broken"].each { |b| out << "  #{b['file']}:#{b['line']}  #{b['error']}\n" }
+    out
+  end
+
+  def self.table(sessions)
+    rows = sessions.map do |s|
+      boot = tokens(s["boot"]) + (s["started_before_cutoff"] ? "*" : "")
+      [s["id"], s["model"].to_s, s["calls"].to_s, boot, tokens(s["last"]), tokens(s["median_step"]),
+       s["big_steps"].to_s, tokens(s["cache_read"]), s["broken"].to_s, s["label"]]
+    end
+    widths = HEADERS.each_index.map { |i| ([HEADERS] + rows).map { |r| r[i].length }.max }
+    lines = ([HEADERS] + rows).map { |r| r.each_with_index.map { |cell, i| cell.ljust(widths[i]) }.join("  ").rstrip }
+    note = sessions.any? { |s| s["started_before_cutoff"] } ? "\n* boot predates the cutoff\n" : ""
+    lines.join("\n") + "\n" + note
+  end
+
+  def self.tokens(count)
+    return "-" if count.nil?
+
+    count.abs >= 1_000 ? format("%.1fk", count / 1_000.0) : count.to_s
+  end
+
+  private_class_method :table, :tokens
+
+  private
+
+  def reset_time
+    return unless File.file?(@rate_limits_path)
+
+    value = JSON.parse(File.read(@rate_limits_path))["resets_at"].to_s
+    return if value.empty?
+
+    value.match?(/\A\d+\z/) ? Time.at(value.to_i).utc : Time.iso8601(value)
+  rescue JSON::ParserError, ArgumentError, TypeError
+    nil
+  end
+
+  def transcripts(cutoff)
+    TRANSCRIPT_GLOBS.flat_map { |glob| Dir.glob(File.join(@transcripts_root, glob)) }
+                    .select { |path| File.mtime(path) >= cutoff }
+                    .sort
+  end
+
+  def summarize(path, cutoff, broken)
+    calls = {}
+    label = nil
+    torn = 0
+    File.foreach(path).with_index(1) do |line, number|
+      next if line.strip.empty?
+
+      record = JSON.parse(line)
+      raise TypeError, "record is not a JSON object" unless record.is_a?(Hash)
+
+      label ||= prompt_line(record)
+      call = call_from(record)
+      next unless call
+
+      calls[call[:id]] = calls.key?(call[:id]) ? call.merge(at: calls[call[:id]][:at]) : call
+    rescue JSON::ParserError
+      torn += 1
+      broken << { "file" => path, "line" => number, "error" => "unparsable JSON" }
+    rescue ArgumentError, TypeError => e
+      torn += 1
+      broken << { "file" => path, "line" => number, "error" => e.message }
+    end
+    row(path, calls.values, cutoff, label, torn)
+  end
+
+  def row(path, calls, cutoff, label, torn)
+    window = calls.each_index.select { |i| calls[i][:at] >= cutoff }
+    return if window.empty? && torn.zero?
+
+    steps = window.filter_map { |i| calls[i][:context] - calls[i - 1][:context] if i.positive? }
+    {
+      "id" => File.basename(path, ".jsonl"),
+      "file" => path,
+      "label" => label || NO_PROMPT,
+      "model" => calls.last && calls.last[:model],
+      "calls" => window.size,
+      "boot" => calls.first && calls.first[:context],
+      "last" => calls.last && calls.last[:context],
+      "median_step" => median(steps),
+      "big_steps" => steps.count { |step| step > BIG_STEP },
+      "cache_read" => window.sum { |i| calls[i][:cache_read] },
+      "broken" => torn,
+      "started_before_cutoff" => !calls.empty? && calls.first[:at] < cutoff,
+    }
+  end
+
+  def call_from(record)
+    return unless record["type"] == "assistant"
+
+    message = record["message"]
+    raise TypeError, "assistant record without a message" unless message.is_a?(Hash)
+    return if message["model"] == SYNTHETIC_MODEL
+
+    usage = message["usage"]
+    raise ArgumentError, "assistant record without message id or usage" unless message["id"] && usage.is_a?(Hash)
+
+    {
+      id: message["id"],
+      model: message["model"],
+      at: Time.iso8601(record["timestamp"].to_s),
+      context: CONTEXT_FIELDS.sum { |field| usage[field].to_i },
+      cache_read: usage["cache_read_input_tokens"].to_i,
+    }
+  end
+
+  def prompt_line(record)
+    return unless record["type"] == "user" && !record["isMeta"]
+
+    text = prompt_text(record["message"].is_a?(Hash) ? record["message"]["content"] : nil)
+    return if text.nil?
+
+    first = text.lines.map(&:strip).find { |line| !line.empty? && !line.start_with?("<") }
+    first && first[0, LABEL_WIDTH]
+  end
+
+  def prompt_text(content)
+    return content if content.is_a?(String)
+    return unless content.is_a?(Array)
+
+    block = content.find { |b| b.is_a?(Hash) && b["type"] == "text" }
+    block && block["text"]
+  end
+
+  def median(values)
+    return if values.empty?
+
+    sorted = values.sort
+    middle = sorted.size / 2
+    sorted.size.odd? ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2
+  end
+end

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