@zalom/plastic 2.0.0-alpha.22 → 2.0.0-alpha.24

package/scripts/graph-measure

@@ -0,0 +1,249 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "date"
+require_relative "lib/savepoint"
+
+# graph-measure - the one read-only executable over the node ledger (intent
+# 343, G10, n2). A subcommand table over one library, following
+# scripts/runner's shape (327 spec): the public verbs are named up front even
+# before every module lands, a flag outside a verb's own vocabulary is
+# refused by name, and each verb's module is required LAZILY inside its own
+# branch so a verb whose module has not landed yet reports plainly instead of
+# taking `intent`, the verb an operator runs constantly, down with it.
+#
+# Usage:
+#   graph-measure <intent|budget|cohorts> <dir> [--format text|json]
+#
+# `intent` (n2) and `budget` (n4) take an INTENT directory. `cohorts` (n5,
+# its model section; n6 adds the rates, the latency and the bar to the same
+# verb) takes a STORE directory instead - the directory holding `id--slug/`
+# intent folders for one project - and is validated against that shape, not
+# `intent_directory?`.
+#
+# Exit codes:
+#   0 - a report rendered (anomalies never change this: a ledger with torn
+#       lines still renders, lists them, and exits 0)
+#   1 - the directory has no savepoint.md to measure at all, named
+#   2 - usage: no args, an unknown subcommand, an unknown flag, or the path
+#       is not the right shape for its verb (an intent directory for
+#       `intent`/`budget`, a store directory for `cohorts`)
+#   3 - the verb's module has not been delivered yet
+module GraphMeasureCLI
+  module_function
+
+  VERBS = %w[intent budget cohorts].freeze
+  SAVEPOINT_FILE = "savepoint.md"
+
+  # verb -> [[ModuleName, lib_file], ...], required lazily inside the verb's
+  # own branch (row 2.6). "budget" and "cohorts" name libraries n4 and n5
+  # ship; requiring them today raises LoadError, caught below.
+  LAZY_MODULES = {
+    "intent" => [["GraphMeasure", "graph_measure"], ["GraphMeasureReport", "graph_measure_report"]],
+    "budget" => [["GraphMeasureBudget", "graph_measure_budget"]],
+    "cohorts" => [["GraphMeasureModels", "graph_measure_models"], ["GraphMeasureCohorts", "graph_measure_cohorts"]],
+  }.freeze
+
+  KNOWN_FLAGS = {
+    "intent" => %w[--format],
+    "budget" => %w[--format],
+    "cohorts" => %w[--format],
+  }.freeze
+
+  # "intent" and "budget" take one intent directory; "cohorts" takes the
+  # store directory that holds many of them (row 5.15).
+  DIR_KIND = { "intent" => :intent, "budget" => :intent, "cohorts" => :store }.freeze
+
+  def usage
+    warn "Usage: graph-measure <#{VERBS.join('|')}> <dir> [--format text|json]"
+  end
+
+  def intent_directory?(dir)
+    dir && File.directory?(dir) && File.exist?(Savepoint.intent_file(dir))
+  end
+
+  def store_directory?(dir)
+    dir && File.directory?(dir)
+  end
+
+  def valid_dir?(verb, dir)
+    DIR_KIND.fetch(verb, :intent) == :store ? store_directory?(dir) : intent_directory?(dir)
+  end
+
+  def opt(args, name)
+    (i = args.index(name)) && args[i + 1]
+  end
+
+  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 verb
+      usage
+      return 2
+    end
+
+    unless VERBS.include?(verb)
+      warn "graph-measure: unknown subcommand #{verb.inspect}"
+      usage
+      return 2
+    end
+
+    dir_arg = args.shift
+    unless valid_dir?(verb, dir_arg && File.expand_path(dir_arg))
+      label = DIR_KIND.fetch(verb, :intent) == :store ? "not a store directory" : "not an intent directory"
+      warn "graph-measure: #{dir_arg.inspect} is #{label}"
+      usage
+      return 2
+    end
+    dir = File.expand_path(dir_arg)
+
+    bad_flag = unrecognized_flag(verb, args)
+    if bad_flag
+      warn "graph-measure: unknown flag #{bad_flag.inspect} for #{verb}"
+      usage
+      return 2
+    end
+
+    format = opt(args, "--format") || "text"
+    unless %w[text json].include?(format)
+      warn "graph-measure: unknown --format #{format.inspect} (use text or json)"
+      usage
+      return 2
+    end
+
+    run_lazy(verb, dir, format)
+  rescue StandardError => e
+    # Row 2.22: a malformed graph.md, a torn ledger, or invalid UTF-8 never
+    # raises out of GraphMeasure or GraphMeasureReport (both are built to
+    # resolve broken data to an anomaly, never an exception) - this is
+    # defence in depth so a defect in either never reaches the owner as a
+    # bare Ruby backtrace.
+    warn "graph-measure: internal error: #{e.message}"
+    1
+  end
+
+  def run_lazy(verb, dir, format)
+    LAZY_MODULES.fetch(verb, []).each { |(_name, file)| require_relative(File.join("lib", file)) }
+  rescue LoadError
+    warn "graph-measure: #{verb} is not yet delivered (its module has not landed)"
+    3
+  else
+    dispatch_lazy(verb, dir, format)
+  end
+
+  def dispatch_lazy(verb, dir, format)
+    case verb
+    when "intent"
+      run_intent(dir, format)
+    when "budget"
+      run_budget(dir, format)
+    when "cohorts"
+      run_cohorts(dir, format)
+    else
+      warn "graph-measure: #{verb}'s module loaded but no dispatcher is wired up yet"
+      3
+    end
+  end
+
+  # M1: the boundary's own config resolution, never GraphMeasureModels' or
+  # GraphMeasureCohorts' (spec D2, both modules' own DI convention). Mirrors
+  # scripts/doctor.rb's own `PLASTIC_HOME` fallback and `load_yaml_safe`
+  # shape exactly, so a missing or malformed config.yml/project.yml resolves
+  # to `{}` (the shipped-default chain), never an exception.
+  def plastic_home
+    ENV.fetch("PLASTIC_HOME") { File.join(Dir.home, ".plastic") }
+  end
+
+  def load_yaml_safe(path)
+    return {} unless path && File.exist?(path)
+
+    YAML.safe_load(File.read(path), permitted_classes: [Date, Time]) || {}
+  rescue StandardError
+    {}
+  end
+
+  def missing_savepoint(dir)
+    savepoint_path = File.join(dir, SAVEPOINT_FILE)
+    return nil if File.exist?(savepoint_path)
+
+    warn "graph-measure: #{savepoint_path} does not exist, nothing to measure"
+    savepoint_path
+  end
+
+  def run_intent(dir, format)
+    # Row 2.5: checked directly, ahead of GraphMeasure.read, which resolves a
+    # missing file to an empty (not absent) record by design (D3) - the CLI
+    # boundary is the only place that can still tell "nothing to measure"
+    # apart from "measured, and it is empty".
+    return 1 if missing_savepoint(dir)
+
+    record = GraphMeasure.read(dir)
+    puts format == "json" ? GraphMeasureReport.render_json(record) : GraphMeasureReport.render_text(record)
+    0
+  end
+
+  def run_budget(dir, format)
+    return 1 if missing_savepoint(dir)
+
+    record = GraphMeasureBudget.read(dir)
+    puts format == "json" ? GraphMeasureBudget.render_json(record) : GraphMeasureBudget.render_text(record)
+    0
+  end
+
+  # Row 2.5's "missing savepoint.md" check does not apply here: `dir` is a
+  # STORE directory (spec D1's "the directory holding id--slug/ intent
+  # folders"), which never carries a savepoint.md of its own.
+  #
+  # n6 adds the rates, the latency and the bar to this same verb, sourced
+  # from `GraphMeasureCohorts`. Its bar section reuses the one
+  # `GraphMeasureModels` walk's `qualified` counts (passed in here) rather
+  # than triggering a second store walk for the same numbers.
+  #
+  # M1 (v1 review): this call used to pass neither `project_config:` nor
+  # `global_config:`, so the model comparison always resolved against
+  # RunnerPolicy's shipped defaults only, never the real project-then-
+  # global-then-default chain the CHANGELOG describes and
+  # `scripts/doctor.rb`'s own `model_requalification_checks` actually reads.
+  # Reproduced: with a `plastic-executor:` override present in global
+  # config, `GraphMeasureModels.read` reports real drift rows while this
+  # verb (unpatched) always reported zero. `GraphMeasure`'s own modules stay
+  # config-free by design (D2's DI convention: they never read disk or ENV
+  # themselves) - this executable is the boundary that is allowed to, the
+  # same role `scripts/doctor.rb` already plays for the same two config
+  # files.
+  #
+  # NEW-4 (v2 review, D22): the project-scope half named `<store>/../project.yml`,
+  # a file whose template carries no `agents:` key at all, so a real
+  # operator override at the file that DOES exist in the wild - the store's
+  # sibling `config.yml` - was silently ignored. The path now comes from
+  # `GraphMeasureModels.project_config_path`, the one function
+  # `scripts/doctor.rb`'s own rule calls too, so the two commands cannot
+  # resolve a different file for the same store.
+  def run_cohorts(dir, format)
+    global_config = load_yaml_safe(File.join(plastic_home, "config.yml"))
+    project_config = load_yaml_safe(GraphMeasureModels.project_config_path(dir))
+
+    models_record = GraphMeasureModels.read(dir, project_config: project_config, global_config: global_config)
+    cohorts_record = GraphMeasureCohorts.read(dir, qualified: models_record[:qualified],
+                                                    project_config: project_config, global_config: global_config)
+    if format == "json"
+      combined = GraphMeasureModels.model(models_record).merge(GraphMeasureCohorts.model(cohorts_record))
+      puts JSON.generate(combined)
+    else
+      puts GraphMeasureModels.render_text(models_record)
+      puts GraphMeasureCohorts.render_text(cohorts_record)
+    end
+    0
+  end
+end
+
+exit GraphMeasureCLI.main(ARGV) if $PROGRAM_NAME == __FILE__

package/scripts/hook-call-budget

@@ -21,10 +21,10 @@
 # transcript, at <dirname(transcript_path)>/<session_id>/subagents/
 # agent-<agent_id>.jsonl (the main transcript_path plus the main session_id
 # plus the subagent's own agent_id): its first user record carries the
-# dispatch prompt, and the lead/spawn block always pastes the node's packet
-# path into that prompt (PACKET_PATH_RE). The packet path names the intent
+# dispatch prompt, and the lead/spawn block always pastes the node's input
+# path into that prompt (INPUT_PATH_RE). The node input path names the intent
 # directory directly (its grandparent), so this hook never scans the store to
-# find it. No packet path in that first prompt means allow.
+# find it. No node input path in that first prompt means allow.
 #
 # The cap applies only when that node's LATEST transition line in
 # <intent>/savepoint.md is `running` and carries `calls=`; a later `done` or
@@ -47,10 +47,10 @@ module HookCallBudget
 
   RETURN_INSTRUCTION = "commit what is green and return failed_verification reason=call_budget"
 
-  # A node id, then "--a", then an attempt number, inside a /packets/
+  # A node id, then "--a", then an attempt number, inside a /attempts/
   # directory: the exact shape RunnerDispatch's spawn block pastes into a
   # subagent's own first prompt. Captures [full_path, node].
-  PACKET_PATH_RE = %r{(\S+/packets/([a-z]{1,2}\d+)--a\d+\.packet)}.freeze
+  INPUT_PATH_RE = %r{(\S+/attempts/([a-z]{1,2}\d+)--a\d+\.input)}.freeze
 
   FIRST_RECORD_SCAN_LIMIT = 20
 
@@ -78,7 +78,7 @@ module HookCallBudget
     end
     return nil unless prompt
 
-    match = PACKET_PATH_RE.match(prompt)
+    match = INPUT_PATH_RE.match(prompt)
     return nil unless match
 
     node = match[2]

package/scripts/hook-capture

@@ -11,9 +11,11 @@
 
 require "json"
 require "open3"
+require "time"
 require "fileutils"
 require_relative "lib/session_ledger"
 require_relative "lib/dashboard_banner"
+require_relative "lib/active_delivery"
 
 raw = begin
   $stdin.read
@@ -47,32 +49,31 @@ def truncate(text, max)
   "#{text[0, max - 3]}..."
 end
 
-# --- (a) tmp root + heartbeat, guarded on the pointer (spec D9) ------------
-# Session start writes the `current` pointer; a capture with no pointer yet
+# --- (a) heartbeat, guarded on the session tmp dir already existing --------
+# Session start creates `.tmp/<sid>/`; a capture with no such directory 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.
+# neither the directory nor its heartbeat is created HERE either.
+# UserPromptSubmit fires before PostToolUse, so capture is the FIRST place
+# this guard matters; hook-record carries the same guard for its own
+# (later) heartbeat write. (344 n2, D4-D5)
 begin
-  if File.exist?(SessionLedger.pointer_path(store, sid))
-    SessionLedger.ensure_tmp_root(store)
-    FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store, sid))
+  if Dir.exist?(SessionLedger.session_tmp_dir(store, sid))
     File.write(SessionLedger.heartbeat_path(store, sid), "#{Time.now.utc.iso8601}\n")
   end
 rescue StandardError
   nil
 end
 
-# --- (b) read the pointer -----------------------------------------------
+# --- (b) a live delivery lock names this session (344 n2, D5, D12) ----------
 skip_day_ledger = false
 begin
-  pointer = SessionLedger.pointer_path(store, sid)
-  if File.exist?(pointer)
-    current = File.read(pointer).strip
-    skip_day_ledger = !current.empty? && current != today
-  end
+  full_session = session_id.empty? ? ENV["CLAUDE_CODE_SESSION_ID"].to_s : session_id
+  skip_day_ledger = !ActiveDelivery.resolve(
+    global_store: store,
+    project_roots: ActiveDelivery.project_roots(plastic_home),
+    session: full_session
+  ).nil?
 rescue StandardError
   nil
 end

package/scripts/hook-record

@@ -16,6 +16,7 @@ require "fileutils"
 require_relative "lib/savepoint"
 require_relative "lib/lock"
 require_relative "lib/session_ledger"
+require_relative "lib/active_delivery"
 
 raw = begin
   $stdin.read
@@ -80,11 +81,20 @@ unless skip_day_ledger
     sid = SessionLedger.short_session_id(nil, session_id)
     today = SessionLedger.day_id
 
+    # A live delivery lock naming this session's full id skips promotion
+    # (344 n2, D5, D12): the lock, not the retired pointer, decides.
     proceed = true
-    pointer = SessionLedger.pointer_path(store, sid)
-    if File.exist?(pointer)
-      current = File.read(pointer).strip
-      proceed = current.empty? || current == today
+    unless session_id.empty?
+      begin
+        held = ActiveDelivery.resolve(
+          global_store: store,
+          project_roots: ActiveDelivery.project_roots(plastic_home),
+          session: session_id
+        )
+        proceed = held.nil?
+      rescue StandardError
+        proceed = true
+      end
     end
 
     if proceed
@@ -135,19 +145,16 @@ unless skip_day_ledger
   end
 end
 
-# --- (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.
+# --- (d) heartbeat, guarded on the session tmp dir (344 n2, D4) ------------
+# Session start creates the per-session tmp directory; with no such
+# directory at all, session start never ran for this session (a `-p` print
+# session, a resumed background job, an unregistered SessionStart hook), so
+# the heartbeat is not written and no directory is created here either --
+# the session tmp directory, created by session start, is the guard.
 begin
   store ||= File.join(plastic_home, "store")
   sid ||= SessionLedger.short_session_id(nil, session_id)
-  if File.exist?(SessionLedger.pointer_path(store, sid))
-    SessionLedger.ensure_tmp_root(store)
-    FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store, sid))
+  if Dir.exist?(SessionLedger.session_tmp_dir(store, sid))
     File.write(SessionLedger.heartbeat_path(store, sid), "#{Time.now.utc.iso8601}\n")
   end
 rescue StandardError

package/scripts/hook-savepoint

@@ -4,7 +4,8 @@
 
 # hook-savepoint (intent 311): the PreCompact hook body. Reads the harness
 # payload from stdin (session_id, cwd), takes the Plastic home from argv,
-# writes this session's hand-off for the pointer's day, and prints one
+# writes this session's hand-off for the session's day from the day ledger,
+# and prints one
 # message: the fixed text, plus the written file's path when a session
 # resolved (both harnesses relay the same launcher and the Codex pin feeds
 # both sides the same payload, so the two stay equal). Always exits 0,
@@ -15,12 +16,31 @@
 require "json"
 require_relative "lib/session_ledger"
 require_relative "lib/handoff"
+require_relative "lib/active_delivery"
 
 MESSAGE = "PLASTIC SAVEPOINT - context is being compacted. The hand-off for this " \
           "session is written in today's day ledger " \
           "(store/.sessions/<day>/handoff--<session>.md). " \
           "After compaction say continue to resume from it."
 
+# The intent this session is delivering, resolved through the same walk the
+# Stop gate uses (row 4.38): read-config's project_roots, plus the global
+# store, glob for a live delivery.lock this session holds. Never raises
+# (ActiveDelivery.resolve rescues its own reads); a lookup failure just
+# means the Runner section is omitted, never that the hand-off is lost.
+def resolve_intent(plastic_home, session_id, read_config_path)
+  return nil if session_id.strip.empty?
+
+  global_store = File.join(plastic_home, "store")
+  roots_raw = IO.popen({ "PLASTIC_HOME" => plastic_home }, [read_config_path, "project_roots"],
+                       err: File::NULL, &:read).to_s.strip
+  project_roots = roots_raw.empty? ? [] : Array(JSON.parse(roots_raw))
+  project_roots = project_roots.map { |root| File.expand_path(root.to_s) }
+  ActiveDelivery.resolve(global_store: global_store, project_roots: project_roots, session: session_id)
+rescue StandardError
+  nil
+end
+
 written = nil
 begin
   plastic_home = ARGV[0].to_s
@@ -30,11 +50,14 @@ begin
   session_id = payload["session_id"].to_s
 
   unless plastic_home.empty? || session_id.strip.empty?
-    store = File.join(File.expand_path(plastic_home), "store")
+    home = File.expand_path(plastic_home)
+    store = File.join(home, "store")
     session = SessionLedger.short_session_id(session_id, nil)
     day = Handoff.day_for(store, session, today: SessionLedger.day_id)
+    read_config_path = File.expand_path("read-config", __dir__)
+    intent = resolve_intent(home, session_id, read_config_path)
     written = Handoff.write(store: store, day: day, session: session, trigger: "precompact",
-                            templates: File.expand_path("../templates", __dir__))
+                            templates: File.expand_path("../templates", __dir__), intent: intent)
   end
 rescue StandardError, JSON::ParserError
   nil

package/scripts/hook-session-start

@@ -7,13 +7,15 @@ require "json"
 require "date"
 require "yaml"
 require "fileutils"
-require_relative "lib/bridge"
 require_relative "lib/boot_banner"
 require_relative "lib/qmd_sync"
 require_relative "lib/doctor_core"
 require_relative "lib/session_ledger"
 require_relative "lib/day_summary"
-require_relative "lib/packet_wrapper"
+require_relative "lib/data_boundary"
+require_relative "lib/active_delivery"
+require_relative "lib/runner_core"
+require_relative "lib/runner_watch"
 
 index_path, plastic_home, mode, plugin_root = ARGV
 exit 0 unless index_path && plastic_home && mode
@@ -233,19 +235,56 @@ begin
     if qmd_status[:present]
       # C23 (intent 341, G8): a QMD hit is untrusted text, so it never sits
       # loose in additionalContext alongside the owner's own banners; it
-      # rides inside PacketWrapper's data boundary.
+      # rides inside DataBoundary's data boundary.
       qmd_line = if qmd_status[:all_registered]
         "QMD: #{qmd_status[:registered].size} Plastic collections indexed (search with the qmd skill)."
       else
         "QMD detected — run `qmd-sync register --all` to index your Plastic stores for search."
       end
-      token = PacketWrapper.boundary_token([qmd_line])
-      parts << PacketWrapper.wrap(qmd_line, label: "qmd-hit", source: "qmd-sync", token: token).rstrip
+      token = DataBoundary.boundary_token([qmd_line])
+      parts << DataBoundary.wrap(qmd_line, label: "qmd-hit", source: "qmd-sync", token: token).rstrip
     end
   rescue Exception
     # Any failure (timeout, missing binary, parse error) — stay silent, never crash.
   end unless subagent_session
 
+  # --- Delivery watch (intent 340a, G7b, n3, graph.md D10) ---
+  # One unrecorded tick (record: false: reclaim and classify, no snapshot,
+  # no record line, so boot never advances a quiet count) per intent
+  # ActiveDelivery.candidate_intent_dirs finds, naming every stalled or
+  # done_unreported one in a single line, nothing when there are none. The
+  # whole block is one guarded unit, like the QMD block above it: a raise or
+  # a hang on any one candidate must add nothing rather than name only the
+  # candidates seen before the failure, so the line a boot does print is
+  # never a partial one.
+  begin
+    Timeout.timeout(2) do
+      roots_raw = IO.popen({ "PLASTIC_HOME" => plastic_home }, [read_config, "project_roots"],
+                            err: File::NULL, &:read).to_s.strip
+      project_roots = roots_raw.empty? ? [] : Array(JSON.parse(roots_raw))
+      project_roots = project_roots.map { |root| File.expand_path(root.to_s) }
+
+      attention = []
+      ActiveDelivery.candidate_intent_dirs(global_store: store_dir, project_roots: project_roots).uniq.each do |dir|
+        watch_context = RunnerCore.context(intent_dir: dir)
+        result = RunnerWatch.tick(watch_context, record: false)
+        next unless %w[stalled done_unreported].include?(result[:class])
+
+        watch_intent_id = File.basename(dir).split("--").first
+        if result[:class] == "stalled"
+          blocker = Array(result[:blockers]).first
+          attention << (blocker ? "#{watch_intent_id} stalled (#{blocker})" : "#{watch_intent_id} stalled")
+        else
+          attention << "#{watch_intent_id} done_unreported"
+        end
+      end
+      parts << "PLASTIC watch: #{attention.join(', ')}" if attention.any?
+    end
+  rescue Exception
+    # Any failure or timeout (a malformed intent directory, a hung tick) -
+    # stay silent, never crash boot.
+  end unless subagent_session
+
   # --- Project (or global) banner with its active intent ---
   # The one piece of intent context a live boot still carries: which store
   # is live, and which intent (if any) is active in it (intent 341, G8, D4).
@@ -349,9 +388,11 @@ begin
     end
   end
 
-  # --- Session day ledger: open or join today, write the per-session pointer
-  # and heartbeat (intent 298, spec D4). Best-effort: any failure here degrades
-  # to no ledger context line, never blocks the session.
+  # --- Session day ledger: open or join today, create the tmp dir and write
+  # the heartbeat (344 n2, spec D4). The per-session state retired: hooks
+  # now ask ActiveDelivery.resolve for a live delivery lock instead.
+  # Best-effort: any failure here degrades to no ledger context line, never
+  # blocks the session.
   unless subagent_session
     begin
       templates = File.expand_path("../templates", __dir__)
@@ -369,8 +410,6 @@ begin
       SessionLedger.ensure_tmp_root(store_dir)
       FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store_dir, sid))
       File.write(SessionLedger.heartbeat_path(store_dir, sid), "#{Time.now.utc.iso8601}\n")
-      pointer = SessionLedger.pointer_path(store_dir, sid)
-      File.write(pointer, "#{day}\n") unless File.exist?(pointer)
 
       checklist = SessionLedger.checklist_path(store_dir, day)
       open_count = 0

package/scripts/hook-stop

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# hook-stop (intent 340b, G7c, n4, D5): the Stop hook body. Reads the harness
+# payload from stdin, gathers the runtime config StopGate needs, and asks it
+# whether this session may stop. Prints Claude Code's Stop block schema on
+# stdout only when the answer is block; a permit prints nothing at all.
+# Registration is static (hooks/hooks.json, settings.json) - this launcher
+# always installs - and the decision is runtime, off by default
+# (runner.stop_hook defaults false), so the owner flips continuation on or
+# off by editing config with no reinstall. Every error permits: always
+# exits 0, never raises out to the harness.
+#
+# Usage: hook-stop <plastic_home>   (stdin: the hook JSON)
+
+require "json"
+require_relative "lib/stop_gate"
+
+plastic_home = ARGV[0]
+exit 0 if plastic_home.nil? || plastic_home.empty?
+
+def read_config_value(key, home, read_config)
+  IO.popen({ "PLASTIC_HOME" => home }, [read_config, key], err: File::NULL, &:read).to_s.strip
+rescue StandardError
+  ""
+end
+
+begin
+  raw = $stdin.tty? ? "" : $stdin.read.to_s
+  payload = raw.strip.empty? ? {} : JSON.parse(raw)
+  payload = {} unless payload.is_a?(Hash)
+
+  home = File.expand_path(plastic_home)
+  global_store = File.join(home, "store")
+  read_config = File.expand_path("read-config", __dir__)
+
+  config_stop_hook = read_config_value("runner.stop_hook", home, read_config)
+  roots_raw = read_config_value("project_roots", home, read_config)
+  project_roots =
+    begin
+      roots_raw.strip.empty? ? [] : Array(JSON.parse(roots_raw))
+    rescue JSON::ParserError
+      []
+    end
+  project_roots = project_roots.map { |root| File.expand_path(root.to_s) }
+
+  session = payload["session_id"].to_s
+
+  result = StopGate.decide(payload: payload, config_stop_hook: config_stop_hook, session: session,
+                           global_store: global_store, project_roots: project_roots)
+
+  puts JSON.generate("decision" => "block", "reason" => result[:reason]) if result[:block]
+rescue StandardError
+  nil
+end
+exit 0