@zalom/plastic 1.14.0 → 2.0.0-alpha.1

package/scripts/append-ledger

@@ -0,0 +1,195 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# append-ledger (intent 297) - the only writer of a session day ledger's
+# shared files. Every verb either appends a line to checklist.md or
+# savepoint.md, or flips one checklist line's state marker byte, always
+# under an exclusive lock on the target file itself (spec D6, D7, D8). Every
+# invocation scaffolds the day itself through SessionLedger.open_day (cheap
+# and idempotent), so a capture that crosses midnight never fails and never
+# needs a second process (spec D12).
+#
+# Usage:
+#   append-ledger pending <summary> [common flags]
+#   append-ledger item <summary> [common flags]
+#   append-ledger promote [--match <substring>] [--savepoint] [common flags]
+#   append-ledger tick [--match <substring>] [--savepoint] [common flags]
+#   append-ledger savepoint --event Item|Done|Note <summary> [common flags]
+#
+# Common flags:
+#   --store <dir>      defaults to $PLASTIC_HOME/store ($PLASTIC_HOME defaults to ~/.plastic)
+#   --day <YYYYMMDD>    defaults to SessionLedger.day_id (today, local wall clock)
+#   --session <id>      defaults to $CLAUDE_CODE_SESSION_ID, then "local"
+#   --project <slug>    defaults to the project_slug derived from --cwd
+#   --cwd <dir>         defaults to Dir.pwd
+#   --templates <dir>   defaults to the templates/ dir shipped next to this script
+#
+# Exit codes:
+#   0 - done
+#   2 - usage error, or promote/tick found nothing to address (no write happens)
+#   3 - promote/tick could not take an exclusive lock (filesystem without flock support)
+
+require_relative "lib/session_ledger"
+
+VERBS = %w[pending item promote tick savepoint].freeze
+
+def usage_abort(message)
+  warn "append-ledger: #{message}"
+  exit 2
+end
+
+# The value token that follows a flag at argv[i]. Aborts with exit 2 rather
+# than silently returning nil when the flag is the last token (a trailing
+# `--store` with nothing after it must not fall back to a default as if the
+# flag had never been given).
+def next_value!(argv, i, flag)
+  usage_abort("#{flag} requires a value") if i + 1 >= argv.length
+  argv[i + 1]
+end
+
+def parse_args(argv)
+  opts = {
+    match: nil, savepoint: false, event: nil,
+    store: nil, day: nil, session: nil, project: nil, cwd: nil, templates: nil,
+  }
+  positional = []
+  i = 0
+  while i < argv.length
+    arg = argv[i]
+    case arg
+    when "--match"     then opts[:match] = next_value!(argv, i, arg); i += 1
+    when "--event"     then opts[:event] = next_value!(argv, i, arg); i += 1
+    when "--store"     then opts[:store] = next_value!(argv, i, arg); i += 1
+    when "--day"       then opts[:day] = next_value!(argv, i, arg); i += 1
+    when "--session"   then opts[:session] = next_value!(argv, i, arg); i += 1
+    when "--project"   then opts[:project] = next_value!(argv, i, arg); i += 1
+    when "--cwd"       then opts[:cwd] = next_value!(argv, i, arg); i += 1
+    when "--templates" then opts[:templates] = next_value!(argv, i, arg); i += 1
+    when "--savepoint" then opts[:savepoint] = true
+    else
+      usage_abort("unknown flag #{arg.inspect}") if arg.start_with?("--")
+
+      positional << arg
+    end
+    i += 1
+  end
+
+  opts[:verb] = positional.shift
+  opts[:summary] = positional.shift
+  opts
+end
+
+def expand(path)
+  File.expand_path(path.to_s.sub(/\A~/, Dir.home))
+end
+
+# Sibling of this script's dir. Works in-repo (<repo>/scripts/append-ledger
+# -> <repo>/templates) and installed (~/.plastic/scripts/append-ledger ->
+# ~/.plastic/templates when present).
+def default_templates_dir
+  File.expand_path("../templates", __dir__)
+end
+
+def sanitized_summary(raw)
+  usage_abort("a summary is required") if raw.nil?
+
+  clean = SessionLedger.sanitize_summary(raw)
+  usage_abort("summary is empty after sanitizing") if clean.empty?
+  clean
+end
+
+def append_checklist_line(state, store, day, session, project, summary)
+  clean = sanitized_summary(summary)
+  line = SessionLedger.checklist_line(state, session, project, clean)
+  path = SessionLedger.checklist_path(store, day)
+  SessionLedger.append_line(path, line, header: SessionLedger.checklist_header(day))
+end
+
+# set_state identifies the target line AND flips it inside one LOCK_EX hold,
+# returning the flipped line's own summary (or nil when nothing matched).
+# There is deliberately no separate identify-then-flip step here: a prior
+# version located the target under its own released lock, then set_state
+# re-located it under a fresh lock, and the two scans could disagree under
+# concurrency, naming the wrong line in the --savepoint entry below. Using
+# set_state's return value is what keeps identify-and-flip atomic.
+def run_transition(from, to, event, store, day, session, project, opts)
+  path = SessionLedger.checklist_path(store, day)
+
+  target_summary =
+    begin
+      SessionLedger.set_state(path, from: from, to: to, session: session, match: opts[:match])
+    rescue SessionLedger::LockUnavailableError => e
+      warn "append-ledger: #{e.message}"
+      exit 3
+    end
+
+  if target_summary.nil?
+    warn "append-ledger: nothing to address"
+    exit 2
+  end
+
+  return unless opts[:savepoint]
+
+  line = SessionLedger.savepoint_line(event, session, project, target_summary, now: Time.now)
+  SessionLedger.append_line(SessionLedger.savepoint_path(store, day), line, header: nil)
+end
+
+def run_savepoint(store, day, session, project, opts)
+  unless SessionLedger::EVENTS.include?(opts[:event])
+    usage_abort("--event must be one of #{SessionLedger::EVENTS.join(", ")}, got #{opts[:event].inspect}")
+  end
+
+  clean = sanitized_summary(opts[:summary])
+  line = SessionLedger.savepoint_line(opts[:event], session, project, clean, now: Time.now)
+  SessionLedger.append_line(SessionLedger.savepoint_path(store, day), line, header: nil)
+end
+
+def main(argv)
+  opts = parse_args(argv)
+  usage_abort("verb must be one of #{VERBS.join(", ")}, got #{opts[:verb].inspect}") unless VERBS.include?(opts[:verb])
+
+  plastic_home = expand(ENV.fetch("PLASTIC_HOME", "~/.plastic"))
+  store = opts[:store] ? expand(opts[:store]) : File.join(plastic_home, "store")
+  templates = opts[:templates] ? expand(opts[:templates]) : default_templates_dir
+  usage_abort("templates dir not found: #{templates}") unless Dir.exist?(templates)
+  cwd = opts[:cwd] ? expand(opts[:cwd]) : Dir.pwd
+
+  day = opts[:day] || SessionLedger.day_id
+  unless SessionLedger.valid_day_id?(day)
+    usage_abort("--day must be eight digits parsing as a real date, got #{day.inspect}")
+  end
+
+  if opts[:project] && !SessionLedger::SLUG_RE.match?(opts[:project])
+    usage_abort("--project must match [a-z0-9-]+, got #{opts[:project].inspect}")
+  end
+
+  session = SessionLedger.short_session_id(opts[:session], ENV["CLAUDE_CODE_SESSION_ID"])
+  project = opts[:project] || SessionLedger.project_slug(cwd, plastic_home: plastic_home)
+
+  # Always call open_day: it is idempotent (File::CREAT | File::EXCL decides
+  # create vs join) and cheap, so this never depends on Dir.exist?(day_dir)
+  # as a proxy for "does the day file exist". A guard keyed on the DIRECTORY
+  # missed the case of a day dir that exists without its <day>.md (a crashed
+  # scaffold, or a template-read failure): that guard would see the
+  # directory, skip open_day forever, and every append would land in a day
+  # dir with no intent file at all.
+  SessionLedger.open_day(store: store, day: day, templates: templates, author: session)
+
+  case opts[:verb]
+  when "pending"
+    append_checklist_line(:pending, store, day, session, project, opts[:summary])
+  when "item"
+    append_checklist_line(:open, store, day, session, project, opts[:summary])
+  when "promote"
+    run_transition(:pending, :open, "Item", store, day, session, project, opts)
+  when "tick"
+    run_transition(:open, :done, "Done", store, day, session, project, opts)
+  when "savepoint"
+    run_savepoint(store, day, session, project, opts)
+  end
+
+  exit 0
+end
+
+main(ARGV) if $PROGRAM_NAME == __FILE__

package/scripts/codex-hook

@@ -2,42 +2,41 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 #
-# Usage: codex-hook <gate>
-#   file-mutation gates: edit-gates | gate-check
-#   live-state hooks (intent 199): session-start | check-update | continue |
-#     future-intent-check | auto-arm | power-tools | savepoint
-#   shell-tool gate (intent 203): bash-gate
+# Usage: codex-hook <hook>
+#   file-mutation hook: record (PostToolUse on apply_patch)
+#   live-state hooks (intent 199, capture/record collapse by 298):
+#     session-start | check-update | capture | savepoint
+#   session-end hook (intent 309): close, handed off detached
 #
-# The Codex input adapter (intent 102, extended by 199, 203, and collapsed by
-# 251). Reads a Codex hook stdin payload once. Three shapes exist and the gate
-# name alone selects which path runs (Codex's own hooks.json registration
-# guarantees they never cross): the apply_patch path reads session_id at top
-# level and the apply_patch command in tool_input.command [guide Part 4],
-# parses the diff envelope once via ApplyPatchEnvelope, and runs all five gates
-# (savepoint-pre, lock-gate, code-gate, links-gate, create-gate) IN-PROCESS
-# through scripts/lib/codex_edit_gates.rb, which drives the same
-# scripts/lib/edit_gates.rb functions Claude's merged dispatcher drives
-# (mirroring intent 244). This replaced five registered PreToolUse commands and
-# three nested run_core children with one process. The live-state hooks carry
-# no tool_input at all (they are not tool calls); the dispatcher execs the SAME
-# launcher file Claude already runs for that hook (hooks/<name>), which is
-# already harness-agnostic (resolves ~/.plastic off $HOME, reads only the
-# common stdin fields the guide confirms Codex shares with Claude for these
-# three events), so the body is reused, not rewritten (D3). The shell-tool gate
-# (bash-gate) reports tool_name: "Bash" with the command in tool_input.command,
-# but MUST NOT be routed through ApplyPatchEnvelope.parse below: a plain shell
-# command has no *** Begin Patch/*** End Patch envelope, so it would parse to
-# an empty op list and hit this file's own `exit 0 if ops.empty?` line,
-# silently allowing every Bash call and reopening the exact hole intent 203
-# closes. So it execs the SAME scripts/hook-bash-gate file Claude already runs,
-# unmodified, the identical "drive the body, relay its output" pattern used for
-# the live-state hooks. The one adaptation shared by both the live-state and
-# shell-tool paths is threading the payload's session_id into
-# CLAUDE_CODE_SESSION_ID, since Codex's own process env never carries it, plus
-# a bounded timeout: hooks/check-update backgrounds a real npm network call
-# without redirecting its output away from the inherited stdout/stderr pipes,
-# and Codex invokes hooks synchronously, so without a bound a slow network call
-# could hold this dispatcher's pipe open past the launcher's own (fast) exit.
+# The Codex input adapter (intent 102, extended by 199, collapsed by 251, cut to
+# the record hook by 302). Reads a Codex hook stdin payload once. Two shapes
+# exist and the hook name alone selects which path runs (Codex's own hooks.json
+# registration guarantees they never cross): the apply_patch path reads
+# session_id at top level and the apply_patch command in tool_input.command
+# [guide Part 4] and parses the diff envelope once via ApplyPatchEnvelope; the
+# live-state hooks carry no tool_input at all (they are not tool calls), so the
+# dispatcher execs the SAME launcher file Claude already runs for that hook
+# (hooks/<name>), which is already harness-agnostic (resolves ~/.plastic off
+# $HOME, reads only the common stdin fields the guide confirms Codex shares with
+# Claude for these events), so the body is reused, not rewritten (D3). The one
+# adaptation on the live-state path is threading the payload's session_id into
+# CLAUDE_CODE_SESSION_ID, since Codex's own process env never carries it, plus a
+# bounded timeout: Codex invokes hooks synchronously, so a launcher that never
+# releases this dispatcher's pipes would hang the session. hooks/check-update
+# used to leak them by backgrounding an npm network call with the inherited
+# descriptors (fixed at the root in intent 289 by redirecting that subshell to
+# /dev/null); the bound stays for any other launcher that misbehaves, and
+# capture_launcher keeps the timeout path silent.
+#
+# The PreToolUse edit-path gates and the Bash-matcher shell gate were removed in
+# 2.0 (intent 302), and the power-tools reminder in intent 309. An older
+# ~/.codex/hooks.json that still names one of them reaches the fail-open `else`
+# below: exit 0, no output, no decision.
+#
+# SessionEnd (intent 309): Codex kills a SessionEnd hook after 3 seconds, so `close`
+# is never relayed synchronously. The dispatcher hands the payload to hooks/close in a
+# detached child (own process group, stdin from a pipe, stdout and stderr to /dev/null)
+# and exits at once; the close hook's own detached filer does the slow part.
 require "json"
 require "open3"
 require "rbconfig"
@@ -50,9 +49,55 @@ require "timeout"
 # caller that merges the dispatcher's own stdout and stderr.
 $stdout.sync = true
 
-STATE_HOOKS = %w[session-start check-update continue future-intent-check auto-arm power-tools savepoint].freeze
+STATE_HOOKS = %w[session-start check-update capture savepoint close].freeze
 STATE_TIMEOUT = 5
-SHELL_HOOKS = %w[bash-gate].freeze
+DETACHED_HOOKS = %w[close].freeze
+
+# One capture path for the relayed-launcher branch (intent 289). The 5 s bound covers a
+# launcher that leaks THIS process's stdout and stderr into a longer-lived background child
+# (hooks/check-update did exactly that before 289): it does not bound a launcher that simply
+# never exits in the foreground, since Open3.popen3's ensure joins the child's wait thread on
+# the way out regardless of Timeout. What is added here is silence on the timeout path. A
+# leaked-pipe launcher leaves Open3's reader threads blocked in IO#read; when Timeout unwinds
+# and popen3's ensure closes those pipes underneath them, both threads raise IOError and Ruby
+# prints a backtrace to real stderr, which any caller merging our stdout and stderr then reads
+# as hook output. Thread#report_on_exception is seeded from the class default AT THREAD
+# CREATION and capture3 creates its readers inside this block (open3.rb:664-665), so
+# clearing the default here is enough. Restored in ensure: nothing else in this process,
+# including a genuinely unexpected exception later, loses its report.
+def capture_launcher(env, *argv, raw:, cwd:)
+  previous = Thread.report_on_exception
+  Thread.report_on_exception = false
+  begin
+    Timeout.timeout(STATE_TIMEOUT) { Open3.capture3(env, *argv, stdin_data: raw, chdir: cwd) }
+  rescue StandardError
+    ["", "", nil] # fail open: launcher missing, unexecutable, crashed, or too slow
+  ensure
+    Thread.report_on_exception = previous
+  end
+end
+
+# Hand a launcher its payload and return without waiting (intent 309). The child gets its
+# own process group so the harness's teardown of this dispatcher never reaches it, reads
+# the payload from a pipe this process fills without blocking and closes, and writes
+# nowhere. Every failure (a missing or unexecutable launcher, a closed pipe) is rescued
+# silently, so nothing ever reaches Codex's stderr from this path.
+def detach_launcher(env, launcher, raw:, cwd:)
+  reader, writer = IO.pipe
+  pid = Process.spawn(env, launcher, in: reader, out: File::NULL, err: File::NULL,
+                      chdir: cwd, pgroup: true)
+  reader.close
+  begin
+    writer.write_nonblock(raw) # a hook payload fits the pipe buffer; a larger one is truncated
+  rescue IO::WaitWritable, SystemCallError
+    nil
+  ensure
+    writer.close
+  end
+  Process.detach(pid)
+rescue StandardError
+  nil # fail open: a close that cannot start is a close the next-day sweep files
+end
 
 gate = ARGV[0].to_s
 raw = ($stdin.read rescue nil)
@@ -67,31 +112,11 @@ if STATE_HOOKS.include?(gate)
   cwd = payload["cwd"].to_s
   cwd = Dir.pwd if cwd.empty? || !Dir.exist?(cwd)
   env = { "CLAUDE_CODE_SESSION_ID" => (session.empty? ? nil : session) }
-  out, err, status = begin
-    Timeout.timeout(STATE_TIMEOUT) { Open3.capture3(env.merge("RUBYOPT" => nil), launcher, stdin_data: raw, chdir: cwd) }
-  rescue StandardError
-    ["", "", nil] # fail open: launcher missing, unexecutable, crashed, or too slow
-  end
-  print out unless out.to_s.empty?
-  warn err unless err.to_s.empty?
-  exit(status ? status.exitstatus : 0)
-end
-
-if SHELL_HOOKS.include?(gate)
-  # bash-gate (intent 203): a shell command has no apply_patch diff envelope, so
-  # this branch execs the SAME scripts/hook-bash-gate file Claude already runs,
-  # unmodified, and relays its exit code and stderr. It must never fall through
-  # to ApplyPatchEnvelope.parse below (see header comment).
-  cwd = payload["cwd"].to_s
-  cwd = Dir.pwd if cwd.empty? || !Dir.exist?(cwd)
-  env = { "CLAUDE_CODE_SESSION_ID" => (session.empty? ? nil : session) }
-  script = File.join(__dir__, "hook-#{gate}")
-  argv = [script]
-  out, err, status = begin
-    Timeout.timeout(STATE_TIMEOUT) { Open3.capture3(env.merge("RUBYOPT" => nil), RbConfig.ruby, *argv, stdin_data: raw, chdir: cwd) }
-  rescue StandardError
-    ["", "", nil] # fail open: script missing, unexecutable, crashed, or too slow
+  if DETACHED_HOOKS.include?(gate)
+    detach_launcher(env.merge("RUBYOPT" => nil), launcher, raw: raw, cwd: cwd) if File.file?(launcher)
+    exit 0
   end
+  out, err, status = capture_launcher(env.merge("RUBYOPT" => nil), launcher, raw: raw, cwd: cwd)
   print out unless out.to_s.empty?
   warn err unless err.to_s.empty?
   exit(status ? status.exitstatus : 0)
@@ -100,48 +125,29 @@ end
 require_relative "lib/apply_patch_envelope"
 
 command = payload.dig("tool_input", "command") || payload.dig("tool_params", "command")
-exit 0 if command.nil? # fail-open: no tool_input at all (unrecognized gate name or non-tool-call payload)
+exit 0 if command.nil? # fail-open: no tool_input at all (unrecognized hook name or non-tool-call payload)
 ops = ApplyPatchEnvelope.parse(command)
-exit 0 if ops.empty? # fail-open: nothing parseable to gate
+exit 0 if ops.empty? # fail-open: nothing parseable to record
 
 CORES = __dir__ # ~/.plastic/scripts
-def run_core(name, *argv)
-  out = IO.popen([{ "RUBYOPT" => nil }, RbConfig.ruby, File.join(CORES, name), *argv], "r", err: [:child, :out], &:read)
-  [out, $?.exitstatus]
-end
 
 case gate
-when "edit-gates"
-  # The ONE registered PreToolUse command on the apply_patch matcher (intent
-  # 251). Five gates, in-process, in Claude's evaluation order, first deny wins,
-  # each deny shape reproduced exactly: stderr plus exit 2 for code-gate,
-  # links-gate and create-gate; stdout permissionDecision JSON plus exit 0 for
-  # lock-gate. Fail-open at both levels, per gate inside EditGates.dispatch and
-  # again at this file's own top level.
-  begin
-    require_relative "lib/codex_edit_gates"
-    exit CodexEditGates.dispatch(ops: ops, payload: payload)
-  rescue StandardError, ScriptError => e
-    # Dispatcher-internal failure: never impersonate a deny. ScriptError (a
-    # sibling of StandardError, not a subclass) covers LoadError: a future
-    # manifest gap (a lib file required here but not distributed, exactly the
-    # bug the full suite caught during this intent's own delivery) must fail
-    # open with a gate decision, never exit 1 with no decision at all.
-    $stderr.puts "plastic codex edit-gates error: #{e.message}"
-    exit 0
-  end
-
-when "gate-check"
-  last_allow = nil
+when "record"
+  # hook-record (intent 298) reads one stdin JSON payload; it takes no ARGV. One
+  # apply_patch call can bundle several file operations, so this synthesizes one
+  # Claude-shaped PostToolUse payload per op and pipes it to hook-record in-process,
+  # mirroring the "drive the body" pattern used for the live-state hooks. record
+  # never blocks and never prints anything (D3), so there is nothing to relay: every
+  # op's failure is independently rescued and the dispatcher always exits 0.
+  cwd_val = payload["cwd"].to_s
   ops.each do |o|
-    out, code = run_core("hook-gate-check", o.path, session)
-    if code == 2
-      print out # {"decision":"block",...}
-      exit 2
+    synth = JSON.generate("session_id" => session, "tool_input" => { "file_path" => o.path }, "cwd" => cwd_val)
+    begin
+      Open3.capture3({ "RUBYOPT" => nil }, RbConfig.ruby, File.join(CORES, "hook-record"), stdin_data: synth)
+    rescue StandardError
+      nil
     end
-    last_allow = out unless out.to_s.strip.empty?
   end
-  print last_allow if last_allow
   exit 0
 
 else

package/scripts/dashboard.rb

@@ -25,7 +25,7 @@ require "json"
 require "yaml"
 require "date"
 require_relative "doctor"
-require_relative "lib/bridge"
+require_relative "lib/savepoint"
 require_relative "lib/lock"
 
 PLASTIC_HOME = ENV.fetch("PLASTIC_HOME") { File.join(Dir.home, ".plastic") }
@@ -36,7 +36,7 @@ def today
 end
 
 # A generic "about a month" threshold, not tuned to any one store's item count.
-# Deliberately independent from plastic-project-continuing's separate stale_threshold_days
+# Deliberately independent from plastic-intent-continuing's separate stale_threshold_days
 # config: that one is a proactive boot-time triage nudge, this is a board annotation.
 # Unifying the two is a follow-up, not this intent.
 STALE_DAYS = 30
@@ -163,7 +163,7 @@ end
 
 # True iff the savepoint ledger's last non-blank line shows real post-birth
 # activity, not just the one-line birth stamp every intent gets at creation
-# (scripts/new-intent's Bridge.append_savepoint call, stage "What"). Reads the
+# (scripts/new-intent's Savepoint.append_savepoint call, stage "What"). Reads the
 # last line, extracts the stage token (second whitespace-separated field, same
 # ledger shape last_accessed_at already parses), and treats any stage other
 # than "What" as progress. Returns false when the file is missing/empty.
@@ -192,7 +192,7 @@ def parse_intent(store_info, dir_name, status_index)
   # Sentinel-aware presence for lifecycle files (intent 60b): a scaffolded
   # placeholder spec/plan/checklist/outcome reads as absent, so a freshly
   # scaffolded intent reports What/Why and is never marked completed/advanced.
-  real = ->(f) { Bridge.stage_file_present?(File.join(dir, f)) }
+  real = ->(f) { Savepoint.stage_file_present?(File.join(dir, f)) }
   body = File.exist?(md) ? File.read(md) : ""
 
   status =