@zalom/plastic 2.0.0-alpha.4 → 2.0.0-alpha.5

package/package.json

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

package/scripts/dashboard.rb

@@ -56,13 +56,26 @@ rescue StandardError
   nil
 end
 
-# Returns the set of intent ids listed under a given INDEX.md section.
+# The link form's id: "- [id](path)...". The class excludes "[" (as well as
+# "]" and whitespace) so this can never match a wikilink line's OWN opening
+# bracket and key it as "[71" (row F, spec 315b): "- [[71]] ..." fails this
+# pattern outright (the character right after "- [" is itself "[", which the
+# class disallows), leaving it to WIKILINK_ID_RE below.
+LINK_ID_RE = /^- \[([^\[\]\s]+)/
+
+# The wikilink form's id: "- [[id]] name (em dash) description (date; ...)",
+# the shape mihradesign's INDEX.md and others use. Bare id, no brackets.
+WIKILINK_ID_RE = /^- \[\[([^\[\]]+)\]\]/
+
+# Returns the set of intent ids listed under a given INDEX.md section, link
+# form and wikilink form alike (row F5: Active, Abandoned, Completed, and a
+# store's Future section can all mix both forms).
 def index_section_ids(index_path, header)
   return [] unless File.exist?(index_path)
   body = File.read(index_path)
   seg = body[/^#{Regexp.escape(header)}\s*\n(.*?)(?=^## |\z)/m, 1]
   return [] unless seg
-  seg.scan(/^- \[([^\]\s]+)/).flatten
+  seg.scan(LINK_ID_RE).flatten + seg.scan(WIKILINK_ID_RE).flatten
 end
 
 # Bug found at intent 202's gate review: the date used to be anchored to the END of the
@@ -77,21 +90,37 @@ end
 # (end-intent's own Bridge.index_entry_match accepts either on read). Because regex
 # alternation is leftmost-first, this only ever matches the date immediately after the
 # link. It never continues scanning into the note prose, so a second date mentioned
-# later in a note's free text cannot be mistaken for the completion date.
-COMPLETION_DATE_RE = /^- \[([^\]\s]+).*?\)\s*[\u2014-]\s*(\d{4}-\d{2}-\d{2})\b/
+# later in a note's free text cannot be mistaken for the completion date. The id class
+# excludes "[" (row F) so this can never fire on a wikilink line's own opening bracket.
+COMPLETION_DATE_RE = /^- \[([^\[\]\s]+).*?\)\s*[\u2014-]\s*(\d{4}-\d{2}-\d{2})\b/
+
+# The wikilink form's completion date: "- [[id]] name (em dash) description
+# (date; other notes)". Real shape (mihradesign's INDEX.md): the date is the
+# first thing inside the entry's trailing parenthetical. A SEPARATE regex
+# from COMPLETION_DATE_RE (row F review finding), not one four-group
+# alternation: a four-group `scan` breaks `String#scan(...).to_h`, and a bare
+# `\(` alternative on the link form would harvest a date out of note prose on
+# an entry with no canonical date of its own.
+WIKILINK_COMPLETION_DATE_RE = /^- \[\[([^\[\]]+)\]\].*?\((\d{4}-\d{2}-\d{2})\b/
 
 # Map of intent id -> completion date string, parsed from the "## Completed" section
-# (lines like "- [12 (em dash) title](link) (em dash) 2026-06-10 optional note text").
-# Deterministic, content-derived. Observability: a populated "## Completed" section that
-# yields not one single dated entry is a parser regression, not a legitimately empty
-# result, so it is surfaced with a stderr warning rather than rotting invisibly (the same
-# silent-failure class intent 202's gate review caught this file already committing).
+# (lines like "- [12 (em dash) title](link) (em dash) 2026-06-10 optional note text",
+# or the wikilink form "- [[12]] title (em dash) description (2026-06-10; notes)").
+# Deterministic, content-derived. Two regexes scanned separately and merged into one
+# hash (row F), so each form's own matching rules stay independent: the wikilink
+# alternative can never steal a date out of a link-form entry's note prose, because it
+# never even looks at a link-form line (its "- [[" anchor cannot match a line whose
+# second character is not itself "["). Observability: a populated "## Completed"
+# section that yields not one single dated entry is a parser regression, not a
+# legitimately empty result, so it is surfaced with a stderr warning rather than
+# rotting invisibly (the same silent-failure class intent 202's gate review caught this
+# file already committing).
 def completion_dates(index_path)
   return {} unless File.exist?(index_path)
   body = File.read(index_path)
   seg = body[/^## Completed\s*\n(.*?)(?=^## |\z)/m, 1] || ""
   entry_count = seg.scan(/^- \[/).size
-  dates = seg.scan(COMPLETION_DATE_RE).to_h
+  dates = seg.scan(COMPLETION_DATE_RE).to_h.merge(seg.scan(WIKILINK_COMPLETION_DATE_RE).to_h)
   if entry_count.positive? && dates.empty?
     warn "dashboard: completion_dates parsed 0/#{entry_count} dates from the " \
          "\"## Completed\" section of #{index_path}; treat this as a parser regression, " \

package/scripts/doctor.rb

@@ -288,6 +288,167 @@ class Doctor
   # content scanning. check_global_store (above) is store/full-scope and includes
   # orphaned_intents / ghost_references, both explicitly forbidden at core by D1.
 
+  # Row E (spec D8, spec 315b): #check_core_files's own `version_match` only ever
+  # compares the SELECTED harness's `<dir>/plastic/VERSION` against the global
+  # VERSION, so a second installed harness left behind on an old version is never
+  # version-checked at all -- exactly how ten stale 1.14.1 Codex registrations
+  # survived a `pass`. This runs the same comparison for EVERY installed harness
+  # (agent_dir on disk), named `version_match_<key>` so the existing `version_match`
+  # name and position stay reserved for the selected harness (pinned tests:
+  # test/doctor_test.rb:1846,1861,1873). Full tier only (`run_checks`); never
+  # `run_core_checks`, which is `binary: true` and runs on the session-start boot
+  # path, where a second-harness warn would become a boot-time error for every user.
+  def check_harness_versions
+    global_version = read_version
+    return [] unless global_version
+
+    agents.filter_map do |key, config|
+      next unless config.is_a?(Hash) && File.directory?(config[:dir].to_s)
+
+      agent_version_path = File.join(config[:dir], "plastic", "VERSION")
+      name = "version_match_#{key}"
+
+      if !File.exist?(agent_version_path)
+        check(
+          category: "core_files", name: name, status: "warn",
+          message: "#{config[:name]}'s agent-side VERSION file not found at #{tilde(agent_version_path)}",
+          fixable: true,
+          fix_hint: "Re-sync the stale harness: npx @zalom/plastic@latest install --reinstall <flag>, or plastic-rollback to a prior version"
+        )
+      else
+        agent_version = File.read(agent_version_path).strip
+        if global_version == agent_version
+          check(
+            category: "core_files", name: name, status: "pass",
+            message: "Global VERSION (#{global_version}) matches #{config[:name]}'s agent-side VERSION"
+          )
+        else
+          check(
+            category: "core_files", name: name, status: "warn",
+            message: "Version mismatch for #{config[:name]}: global=#{global_version}, agent=#{agent_version}",
+            details: [
+              "#{tilde(File.join(plastic_home, "VERSION"))}: #{global_version}",
+              "#{tilde(agent_version_path)}: #{agent_version}",
+            ],
+            fixable: true,
+            fix_hint: "Re-sync the stale harness: npx @zalom/plastic@latest install --reinstall <flag>, or plastic-rollback to a prior version"
+          )
+        end
+      end
+    end
+  end
+
+  # The Codex hook NAME expected per event, keyed off HookRegistry's own
+  # constants rather than a full built command string: naming it, not the
+  # literal dispatcher path, is what #check_codex_stale_registrations needs,
+  # so this never depends on plastic_home resolving to the same install the
+  # live hooks.json's commands were written under.
+  def codex_expected_names_by_event
+    names = {}
+    post_order = HookRegistry.events["PostToolUse"].flat_map { |g| g["hooks"].map { |h| h["name"] } }
+    names["PostToolUse"] = HookRegistry::CODEX_POST_HOOKS & post_order
+
+    HookRegistry::CODEX_LIVE_STATE_EVENTS.each do |event|
+      names[event] = HookRegistry.events[event].flat_map { |g| g["hooks"].map { |h| h["name"] } }
+    end
+
+    end_order = HookRegistry.events["SessionEnd"].flat_map { |g| g["hooks"].map { |h| h["name"] } }
+    names["SessionEnd"] = HookRegistry::CODEX_SESSION_END_HOOKS & end_order
+    names
+  end
+
+  # Row E (spec D8, spec 315b): #codex_hooks_registered_check computes
+  # `want - got` and iterates `expected.each`, so it can see a MISSING registration
+  # but never an EXTRA one, and it can never even visit an event `expected` does not
+  # list at all (a retired event such as PreToolUse, which a stale ~/.codex/hooks.json
+  # can still carry). This scans the UNION of expected and live event keys instead, so
+  # a stale registration parked in a retired event is visible. Compares hook NAMES
+  # (see #codex_expected_names_by_event), not full command strings: a full-command
+  # comparison would embed this Doctor instance's own `plastic_home` in the expected
+  # dispatcher path, which is only guaranteed to match the live hooks.json's own
+  # dispatcher path in a real, single install, never a test that fakes one without the
+  # other. Full tier only (`run_checks`); never `run_core_checks` (D8).
+  #
+  # Post-execution review item 5: name-only comparison alone is blind to two real
+  # cases, both closed here without reintroducing any plastic_home coupling: (a) the
+  # SAME (event, name) pair registered more than once (each copy's name is
+  # individually expected, so a "not in the expected set" scan never sees the
+  # duplicate), and (b) a correctly-named entry whose dispatcher path is an OLD
+  # install, different from the path every OTHER Plastic entry in this same file
+  # actually uses -- the "correct" path here is whichever path the file's own
+  # majority of entries already agrees on, never a path this Doctor instance derives
+  # from its own plastic_home.
+  def check_codex_stale_registrations
+    config = agents["codex"]
+    return [] unless config.is_a?(Hash) && File.directory?(config[:dir].to_s)
+
+    home_dir = config[:home_dir] || config[:dir]
+    hooks_json = File.join(home_dir, "hooks.json")
+    data = read_json_safe(hooks_json)
+    return [] if data.nil? || !data.is_a?(Hash)
+
+    expected_names = codex_expected_names_by_event
+    live = data["hooks"].is_a?(Hash) ? data["hooks"] : {}
+
+    # One pass over every live Plastic entry (event, hook name, and the literal
+    # dispatcher-path token it actually invokes), shared by all three checks below.
+    entries = []
+    (expected_names.keys | live.keys).each do |event|
+      Array(live[event]).each do |group|
+        Array(group["hooks"]).each do |h|
+          cmd = h["command"]
+          next unless HookRegistry.codex_purge_command?(cmd)
+
+          dispatcher_path = cmd.to_s.split(/\s+/).reject(&:empty?).first.to_s.delete("\"'")
+          name = HookRegistry.command_basenames(cmd).last
+          entries << { event: event, name: name, dispatcher_path: dispatcher_path, cmd: cmd }
+        end
+      end
+    end
+
+    stale = []
+
+    # Not in the expected name set for this event at all (the original check).
+    entries.each do |e|
+      want_names = Array(expected_names[e[:event]])
+      stale << "#{e[:event]}: #{e[:cmd]}" unless want_names.include?(e[:name])
+    end
+
+    # (a) the same (event, name) pair registered more than once.
+    entries.group_by { |e| [e[:event], e[:name]] }.each_value do |group|
+      next if group.size <= 1
+
+      group.each { |e| stale << "#{e[:event]}: #{e[:cmd]} (duplicate registration of #{e[:name]})" }
+    end
+
+    # (b) a dispatcher path that differs from the path every other Plastic entry in
+    # this same file actually uses.
+    unless entries.empty?
+      majority_path = entries.map { |e| e[:dispatcher_path] }.tally.max_by { |(_path, count)| count }&.first
+      entries.each do |e|
+        next if e[:dispatcher_path] == majority_path
+
+        stale << "#{e[:event]}: #{e[:cmd]} (dispatcher path #{e[:dispatcher_path]} differs from " \
+                  "this file's other Plastic entries at #{majority_path})"
+      end
+    end
+
+    stale.uniq!
+
+    if stale.empty?
+      [check(
+        category: "agent_registration", name: "codex_stale_registrations", status: "pass",
+        message: "No stale Plastic Codex registrations found outside the expected hook set"
+      )]
+    else
+      [check(
+        category: "agent_registration", name: "codex_stale_registrations", status: "warn",
+        message: "#{stale.size} stale Codex registration(s) found outside the expected hook set",
+        details: stale, fixable: true,
+        fix_hint: "Re-run the Plastic installer with --codex --reinstall to purge stale entries"
+      )]
+    end
+  end
   # --- Check category 2: Conventions ---
 
   # When `scopes` is a non-nil Array of scope strings (e.g. ["global"] or
@@ -2235,6 +2396,8 @@ end
     all_checks += check_conventions(scopes: ["global"])
     all_checks += check_agent_registration(agent_key)
     all_checks += check_core_files(agent_key)
+    all_checks += check_harness_versions
+    all_checks += check_codex_stale_registrations
     all_checks += check_deprecations
     all_checks += check_config_asks(agent_key)
     all_checks += check_qmd

package/scripts/hook-capture

@@ -129,11 +129,20 @@ def truncate(text, max)
   "#{text[0, max - 3]}..."
 end
 
-# --- (a) tmp root + heartbeat, unconditional -------------------------------
+# --- (a) tmp root + heartbeat, guarded on the pointer (spec D9) ------------
+# Session start writes the `current` pointer; a capture with no pointer yet
+# means session start never ran for this session at all (a `-p` print
+# session, a resumed background job, an unregistered SessionStart hook), so
+# neither the per-session dir nor its heartbeat is created. UserPromptSubmit
+# fires before PostToolUse, so capture is the FIRST creator of every orphan
+# `.tmp/<sid>/` this guard prevents; hook-record carries the same guard for
+# its own (later) heartbeat write.
 begin
-  SessionLedger.ensure_tmp_root(store)
-  FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store, sid))
-  File.write(SessionLedger.heartbeat_path(store, sid), "#{Time.now.utc.iso8601}\n")
+  if File.exist?(SessionLedger.pointer_path(store, sid))
+    SessionLedger.ensure_tmp_root(store)
+    FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store, sid))
+    File.write(SessionLedger.heartbeat_path(store, sid), "#{Time.now.utc.iso8601}\n")
+  end
 rescue StandardError
   nil
 end
@@ -151,11 +160,14 @@ rescue StandardError
 end
 
 # --- (c) pending checklist line -------------------------------------------
+# Gated on SessionLedger.capture_worthy?(prompt) (spec D2), a pure predicate
+# over the RAW prompt so it sees the true first character and multi-line
+# shape; the line text itself is still the sanitized, truncated copy.
 unless skip_day_ledger
   begin
-    project = SessionLedger.project_slug(cwd, plastic_home: plastic_home)
-    clean = truncate(SessionLedger.sanitize_summary(prompt), 120)
-    if clean.length >= 10
+    if SessionLedger.capture_worthy?(prompt)
+      project = SessionLedger.project_slug(cwd, plastic_home: plastic_home)
+      clean = truncate(SessionLedger.sanitize_summary(prompt), 120)
       SessionLedger.open_day(store: store, day: today, templates: templates, author: sid)
       line = SessionLedger.checklist_line(:pending, sid, project, clean)
       SessionLedger.append_line(SessionLedger.checklist_path(store, today), line,

package/scripts/hook-record

@@ -135,13 +135,21 @@ unless skip_day_ledger
   end
 end
 
-# --- (d) heartbeat, always -------------------------------------------------
+# --- (d) heartbeat, guarded on the pointer (spec D9) -----------------------
+# Session start writes the `current` pointer; with no pointer at all, session
+# start never ran for this session (a `-p` print session, a resumed
+# background job, an unregistered SessionStart hook), so neither the
+# per-session dir nor its heartbeat is created here -- guarding only the
+# write would still leave an empty directory that heartbeat_age's mtime
+# fallback reports as an orphan just the same.
 begin
   store ||= File.join(plastic_home, "store")
   sid ||= SessionLedger.short_session_id(nil, session_id)
-  SessionLedger.ensure_tmp_root(store)
-  FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store, sid))
-  File.write(SessionLedger.heartbeat_path(store, sid), "#{Time.now.utc.iso8601}\n")
+  if File.exist?(SessionLedger.pointer_path(store, sid))
+    SessionLedger.ensure_tmp_root(store)
+    FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store, sid))
+    File.write(SessionLedger.heartbeat_path(store, sid), "#{Time.now.utc.iso8601}\n")
+  end
 rescue StandardError
   nil
 end

package/scripts/hook-session-start

@@ -18,6 +18,24 @@ require_relative "lib/day_summary"
 index_path, plastic_home, mode, plugin_root = ARGV
 exit 0 unless index_path && plastic_home && mode
 
+# --- session id: the stdin payload's session_id, then the env var, then the
+# pid (spec 298 D1, row G, spec D4). Guarded on $stdin.tty? so a human running
+# this hook by hand at a real terminal never blocks on a read that never gets
+# an EOF; every real harness invocation pipes the SessionStart JSON payload,
+# never attaches a tty. Malformed or empty stdin (or no payload id) falls
+# through to the same env-var-then-pid chain this always had.
+stdin_payload = begin
+  if $stdin.tty?
+    nil
+  else
+    raw = $stdin.read
+    raw && !raw.strip.empty? ? JSON.parse(raw) : nil
+  end
+rescue StandardError
+  nil
+end
+payload_session_id = stdin_payload.is_a?(Hash) ? stdin_payload["session_id"].to_s : ""
+
 # Plastic home and the store are two different paths (intent 231). The shim passes
 # home (~/.plastic) as argument 2; the store lives one level below it. Compose the
 # store exactly once here, so no later line re-derives it and no path can gain a
@@ -361,7 +379,11 @@ begin
   author = "session" if author.empty?
   SessionLedger.open_day(store: store_dir, day: day, templates: templates, author: author)
 
-  session = ENV["CLAUDE_CODE_SESSION_ID"] || Process.pid.to_s
+  session = if !payload_session_id.empty?
+              payload_session_id
+            else
+              ENV["CLAUDE_CODE_SESSION_ID"] || Process.pid.to_s
+            end
   sid = SessionLedger.short_session_id(nil, session)
   SessionLedger.ensure_tmp_root(store_dir)
   FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store_dir, sid))

package/scripts/lib/doctor_session_ledger.rb

@@ -18,6 +18,18 @@ require_relative "session_ledger"
 module DoctorSessionLedger
   ORPHAN_TTL_SECONDS = 24 * 60 * 60
 
+  # Row H (spec D9): a `.tmp/<sid>/` directory with no `current` pointer is a
+  # DIFFERENT orphan class than ORPHAN_TTL_SECONDS's -- a session where
+  # session start never ran at all (a `-p` print session, a resumed
+  # background job, an unregistered SessionStart hook), not a session that
+  # ran and then never closed. No choice of session id ever creates a
+  # pointer for that class, so it would otherwise stay invisible for the
+  # full 24 hours (or forever, once hook-capture/hook-record stop creating
+  # it at all). Short relative to ORPHAN_TTL_SECONDS on purpose: a session
+  # between its own start and its first pointer write is normal and must not
+  # be flagged, but that window is seconds, not hours.
+  NO_POINTER_TTL_SECONDS = 5 * 60
+
   # Seconds since the session's last heartbeat: the ISO-8601 content of `heartbeat`,
   # else that file's mtime, else the directory's mtime.
   def heartbeat_age(dir, now)
@@ -37,6 +49,7 @@ module DoctorSessionLedger
 
     store_dir = File.join(plastic_home, "store")
     orphans = orphaned_session_dirs(store_dir, now)
+    no_pointer = no_pointer_session_dirs(store_dir, now)
     shape = day_ledger_shape_problems(store_dir)
 
     checks = []
@@ -54,6 +67,20 @@ module DoctorSessionLedger
                                 "session is gone: a live session rewrites its heartbeat on every " \
                                 "prompt and edit, so only a listed directory may be removed, by hand.")
               end
+    checks << if no_pointer.empty?
+                check(category: "session_ledger", name: "no_pointer_session_tmp", status: "pass",
+                      message: "No .tmp/<session>/ directory has gone without a `current` pointer for " \
+                               "longer than #{NO_POINTER_TTL_SECONDS} seconds")
+              else
+                check(category: "session_ledger", name: "no_pointer_session_tmp", status: "warn",
+                      message: "#{no_pointer.size} .tmp/<session>/ director#{no_pointer.size == 1 ? "y" : "ies"} " \
+                               "with no `current` pointer for longer than #{NO_POINTER_TTL_SECONDS} seconds " \
+                               "(session start never ran for this session)",
+                      details: no_pointer, fixable: true,
+                      fix_hint: "Remove each listed .tmp/<session>/ directory after confirming that " \
+                                "session never started: no `current` pointer means session start never " \
+                                "ran for it, so this is not a live session missing a checklist entry.")
+              end
     checks << if shape.empty?
                 check(category: "session_ledger", name: "day_ledger_shape", status: "pass",
                       message: "Every .sessions/ entry is a YYYYMMDD day directory with its <day>.md file")
@@ -86,6 +113,31 @@ module DoctorSessionLedger
     [] # unreadable .tmp/: nothing to report, never a crash
   end
 
+  # Row H (spec D9): `.tmp/<sid>/` directories with no `current` pointer, past
+  # NO_POINTER_TTL_SECONDS. A different signal than #orphaned_session_dirs:
+  # that one is age-only and blind to whether a pointer exists at all, so a
+  # young no-pointer dir (a session between its start and its first pointer
+  # write) must not appear here even though it may well appear there once it
+  # ages past ORPHAN_TTL_SECONDS -- the two checks answer different questions
+  # and a dir can legitimately show up in neither, either, or both.
+  def no_pointer_session_dirs(store_dir, now)
+    tmp_root = SessionLedger.tmp_root(store_dir)
+    return [] unless File.directory?(tmp_root)
+
+    Dir.children(tmp_root).sort.filter_map do |name|
+      dir = File.join(tmp_root, name)
+      next unless File.directory?(dir)
+      next if File.exist?(File.join(dir, "current"))
+
+      age = heartbeat_age(dir, now)
+      next if age <= NO_POINTER_TTL_SECONDS
+
+      "global: #{dir} (session #{name}, no `current` pointer, last heartbeat #{age.round}s ago)"
+    end
+  rescue SystemCallError
+    [] # unreadable .tmp/: nothing to report, never a crash
+  end
+
   def day_ledger_shape_problems(store_dir)
     root = SessionLedger.sessions_root(store_dir)
     return [] unless File.directory?(root)

package/scripts/lib/installer_core.rb

@@ -76,8 +76,25 @@ class InstallerCore
     @agents = agents
   end
 
+  # Reads the package version from `package.json` when present (the source
+  # tree, and any dev checkout), falling back to the bare `VERSION` file the
+  # installer copies to `~/.plastic` (row B, spec 315b): an installed system
+  # carries VERSION but never package.json, so `rollback.rb` and `update.rb`
+  # constructing an InstallerCore with `package_root: ~/.plastic` crashed with
+  # a raw Errno::ENOENT before this fallback existed. Raises a named error,
+  # not a bare ENOENT, when neither file exists, so the caller is not
+  # misdirected toward the wrong missing file.
   def read_package_version(root)
-    File.read(File.join(root, "package.json")).then { |s| JSON.parse(s)["version"] }
+    package_json = File.join(root, "package.json")
+    version_file = File.join(root, "VERSION")
+
+    if File.exist?(package_json)
+      JSON.parse(File.read(package_json))["version"]
+    elsif File.exist?(version_file)
+      File.read(version_file).strip
+    else
+      raise "cannot determine the package version: neither #{package_json} nor #{version_file} exists"
+    end
   end
 
   # --- Channel derivation (the channel is encoded in the version string) ---

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

@@ -186,6 +186,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.