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

package/scripts/lib/graph_measure_budget.rb

@@ -6,27 +6,28 @@ require "json"
 require "tmpdir"
 require_relative "node_ledger"
 require_relative "node_file"
-require_relative "node_packet"
-require_relative "packet_wrapper"
+require_relative "node_input"
+require_relative "node_input_compatibility"
+require_relative "data_boundary"
 
 # GraphMeasureBudget (intent 343, G10, n4): whether the `budget:` a node's
 # envelope declares (327 C19, D47) is a ceiling that ever actually held.
-# Intent 340 found at 22:14Z on 2026-09-10 that every runner-built packet
+# Intent 340 found at 22:14Z on 2026-09-10 that every runner-built node input
 # was capped at 8000 tokens whatever the node declared (v1 major M7); this
 # module is the measurement of whether that still holds, from the ledger
-# and the real packet files alone.
+# and the real input files alone.
 #
 # Read-only (spec D2): it opens `nodes/*.md`, `savepoint.md` and files under
-# `packets/`, and writes nothing. A measure with no source prints
-# `:unavailable`, never zero and never blank (spec D3); a packet file named
-# by `packet=` that is not on disk is counted and named by its sha, never
+# `attempts/`, and writes nothing. A measure with no source prints
+# `:unavailable`, never zero and never blank (spec D3); a input file named
+# by `input=` that is not on disk is counted and named by its sha, never
 # silently treated as zero bytes (spec D4).
 #
 # Adds no second parser and no second estimator: `NodeLedger` owns the
 # transition-line format, `NodeFile` owns the envelope's `budget:`,
-# `NodePacket` owns packet path resolution and attempt numbering, and
-# `PacketWrapper.estimate_tokens` is the one token formula, the same the
-# packet builder enforced with (spec D8).
+# `NodeInput` owns node input path resolution and attempt numbering, and
+# `DataBoundary.estimate_tokens` is the one token formula, the same the
+# input builder enforced with (spec D8).
 module GraphMeasureBudget
   module_function
 
@@ -35,7 +36,7 @@ module GraphMeasureBudget
 
   # {ok:, nodes: {id => {declared_budget:, attempts: [...]}}, ceiling: {...}}.
   # Never raises: a missing savepoint.md, a node with no envelope file, and a
-  # packet= naming a file that does not exist on disk all resolve to
+  # input= naming a file that does not exist on disk all resolve to
   # `:unavailable` fields rather than an exception.
   def read(intent_dir, node_reader: NodeFile.method(:parse))
     dir = File.expand_path(intent_dir.to_s)
@@ -54,12 +55,12 @@ module GraphMeasureBudget
       declared_budget = declared_budget_for(dir, subject, node_reader)
       attempts = indices.map do |idx|
         entry = entries[idx]
-        # Row 4.5: the attempt number is NodePacket's own count of non-torn
+        # Row 4.5: the attempt number is NodeInput's own count of non-torn
         # `running` lines up to and including this one, never
         # ReadySet.attempts_count (which resets after `done`, `superseded`
         # or `abandoned` and answers "attempts left", not "which attempt was
         # this line").
-        attempt_number = NodePacket.compute_attempt_number(
+        attempt_number = NodeInput.compute_attempt_number(
           intent_dir: dir, node: subject, lease_flag_given: false, entries: entries[0..idx]
         )
         build_attempt(dir, subject, attempt_number, entry, declared_budget)
@@ -105,9 +106,9 @@ module GraphMeasureBudget
   def attempt_model(a)
     {
       "attempt" => a[:attempt],
-      "packet_sha_declared" => av(a[:packet_sha_declared]),
+      "input_sha_declared" => av(a[:input_sha_declared]),
       "file_exists" => a[:file_exists],
-      "packet_sha_actual" => av(a[:packet_sha_actual]),
+      "input_sha_actual" => av(a[:input_sha_actual]),
       "sha_match" => a[:sha_match],
       "bytes" => av(a[:bytes]),
       "estimate_tokens" => av(a[:estimate_tokens]),
@@ -132,7 +133,7 @@ module GraphMeasureBudget
   def node_block(nodes)
     lines = ["== Budget =="]
     if nodes.empty?
-      lines << "(no packet attempts recorded)"
+      lines << "(no node input attempts recorded)"
       return lines
     end
 
@@ -179,7 +180,7 @@ module GraphMeasureBudget
   # n5's `GraphMeasureModels` already uses for its own `present?` and
   # `resolve_kind`): a local copy, not a second parser or a reopen.
   def declared_budget_for(dir, node, node_reader)
-    path = NodePacket.find_node_path(dir, node)
+    path = NodeInput.find_node_path(dir, node)
     return :unavailable unless path
 
     parsed = with_safe_path(path) { |p| p ? node_reader.call(p) : nil }
@@ -209,22 +210,22 @@ module GraphMeasureBudget
 
   def build_attempt(dir, subject, attempt_number, entry, declared_budget)
     fields = entry[:fields] || {}
-    packet_sha_declared = present?(fields["packet"]) ? fields["packet"] : :unavailable
+    input_sha_declared = present?(fields["input"]) ? fields["input"] : :unavailable
     # D8: hop= is written once, on the running line; absent means no hop
     # block was appended (the feature predates this line, or hop is off),
     # never an unknown quantity to subtract.
     hop = present?(fields["hop"]) ? fields["hop"].to_i : 0
-    path = NodePacket.packet_path(intent_dir: dir, node: subject, attempt: attempt_number)
+    path = NodeInputCompatibility.input_path(intent_dir: dir, node: subject, attempt: attempt_number)
     file_exists = File.exist?(path)
 
     if file_exists
       raw = File.binread(path)
       bytes = raw.bytesize
       sha_actual = Digest::SHA256.hexdigest(raw)[0, 12]
-      estimate = PacketWrapper.estimate_tokens(raw)
+      estimate = DataBoundary.estimate_tokens(raw)
       effective = estimate - hop
       over_budget = declared_budget.is_a?(Integer) ? effective > declared_budget : :unavailable
-      sha_match = sha_actual == packet_sha_declared
+      sha_match = sha_actual == input_sha_declared
     else
       bytes = :unavailable
       sha_actual = :unavailable
@@ -236,10 +237,10 @@ module GraphMeasureBudget
 
     {
       attempt: attempt_number,
-      packet_sha_declared: packet_sha_declared,
-      packet_path: path,
+      input_sha_declared: input_sha_declared,
+      input_path: path,
       file_exists: file_exists,
-      packet_sha_actual: sha_actual,
+      input_sha_actual: sha_actual,
       sha_match: sha_match,
       bytes: bytes,
       estimate_tokens: estimate,
@@ -258,13 +259,13 @@ module GraphMeasureBudget
 
   # --- the suspected ceiling: spec matrix rows 4.8, 4.9 -----------------------
 
-  # A run of packets whose estimates all fall under one value well below
+  # A run of node inputs whose estimates all fall under one value well below
   # their own declared budgets (row 4.8): the candidate ceiling is the
   # largest effective estimate among the usable attempts (every attempt
-  # whose declared budget and packet file are both known), and it is only
+  # whose declared budget and input file are both known), and it is only
   # reported when that value sits strictly under EVERY one of those
   # attempts' own declared budgets - never a "cluster within a few percent"
-  # of each other, which never fires against a real spread of packet sizes.
+  # of each other, which never fires against a real spread of node input sizes.
   # Row 4.9: fewer than two distinct nodes never reports a ceiling; one
   # node's own repeated attempts are not evidence of a ceiling shared across
   # the intent.
@@ -280,7 +281,7 @@ module GraphMeasureBudget
   # "Well below" needs a stated threshold: WELL_BELOW_RATIO is that
   # threshold, and a ceiling is reported only when the candidate uses no
   # more than this fraction of EVERY usable attempt's own declared budget.
-  # Reproduced against 340's real packets: declared budgets there run from
+  # Reproduced against 340's real node inputs: declared budgets there run from
   # 50000 to 160000 tokens (327 D47's per-kind defaults), and every
   # attempt's effective token count clusters between 3380 and 7717 - the
   # candidate (7717) is at most 7717/50000 = 15.4% of even the SMALLEST

package/scripts/lib/handoff.rb

@@ -38,15 +38,11 @@ module Handoff
     File.join(SessionLedger.day_dir(store, day), "handoff--#{session}.md")
   end
 
-  # The day this session's hand-off belongs to: the pointer's day id when
-  # the pointer holds one, else today (no pointer, or a pointer naming an
-  # intent), the same fallback SessionClose uses for the drop at close.
+  # The day this session's hand-off belongs to: the session's day from the
+  # day ledger (SessionLedger.session_day, graph.md D7), the same lookup
+  # SessionClose uses for the drop at close.
   def day_for(store, session, today:)
-    path = SessionLedger.pointer_path(store, session)
-    return today unless File.exist?(path)
-
-    value = File.read(path).strip
-    SessionLedger.valid_day_id?(value) ? value : today
+    SessionLedger.session_day(store, session, today: today)
   end
 
   def clip(summary)

package/scripts/lib/harness_adapter.rb

@@ -64,7 +64,7 @@ module HarnessAdapter
   # squashed (whitespace collapsed, matrix row 1.18) before it is even
   # compared, so a config-authored value carrying a tab or a newline can
   # never reach `NodeLedger` unsquashed and raise `ArgumentError` mid-dispatch,
-  # after the packet is already built. A value that still is not one of
+  # after the node input is already built. A value that still is not one of
   # KNOWN_KEYS after squashing falls back to DEFAULT_KEY with a warning
   # (never to no adapter), so this method's return is always one of the two
   # known, clean strings - safe to hand straight to a ledger field.
@@ -101,7 +101,7 @@ module HarnessAdapter
   # list (matrix row 1.14: a step that dispatched nothing prints no
   # instruction block for a session to act on). `dispatched` is the runner's
   # own plan entries (RunnerDispatch's `:dispatched` shape): [{node:, kind:,
-  # role:, model:, worktree:, packet:}, ...]. The model and the packet path
+  # role:, model:, worktree:, input:}, ...]. The model and the node input path
   # ride straight from each entry - never a fresh lookup (matrix row 1.11)
   # and never a summary (matrix row 1.12) - and `return_contract` (the exact
   # text RunnerDispatch::RETURN_CONTRACT already carries in the YAML plan)
@@ -115,11 +115,11 @@ module HarnessAdapter
   end
 
   # The Claude Code rendering (spec Approach): per dispatched node, the agent
-  # type from the kind, the model the plan already resolved, and the packet
+  # type from the kind, the model the plan already resolved, and the node input
   # path as the whole prompt.
   def render_claude_code(entries, return_contract)
     blocks = entries.map do |d|
-      "Dispatch #{agent_type_for_kind(d[:kind])} for #{d[:node]} (model: #{d[:model]}):\n  prompt: #{d[:packet]}"
+      "Dispatch #{agent_type_for_kind(d[:kind])} for #{d[:node]} (model: #{d[:model]}):\n  prompt: #{d[:input]}"
     end
     "#{return_contract.to_s.strip}\n\n#{blocks.join("\n\n")}\n"
   end
@@ -128,13 +128,13 @@ module HarnessAdapter
   # The Codex rendering: a Codex node runs end to end through `scripts/
   # node-run` (n6), which reads the ledger's own `running` line directly and
   # never through this printed block - so this names, per node, the same
-  # facts the block gives Claude Code (kind, model, packet path) framed as
+  # facts the block gives Claude Code (kind, model, node input path) framed as
   # `node-run` calls, proving the seam renders SOMETHING for the second
   # harness rather than nothing (matrix row 1.27), without inventing detail
   # that belongs to n6's own adapter.
   def render_codex(entries, return_contract)
     blocks = entries.map do |d|
-      "node-run #{d[:node]} (#{d[:kind]}, model: #{d[:model]}):\n  packet: #{d[:packet]}"
+      "node-run #{d[:node]} (#{d[:kind]}, model: #{d[:model]}):\n  input: #{d[:input]}"
     end
     "#{return_contract.to_s.strip}\n\n#{blocks.join("\n\n")}\n"
   end

package/scripts/lib/index_entry.rb

@@ -0,0 +1,53 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# IndexEntry - the shared INDEX.md entry matcher and Active check (intent 188,
+# D12/D13; moved off the retired shared-helpers module by intent 344, D2).
+#
+# ONE definition site for the "- [ID <sep> Title](link)" shape both `active?`
+# (below) and `scripts/end-intent`'s own INDEX-move parser depend on, so the
+# two regexes can never drift apart. Accepts a real em dash (U+2014) OR a
+# plain hyphen as the id/title separator on READ; every WRITE still emits the
+# real em dash (D10). The separator is built from the codepoint, not a
+# literal byte, so this file stays em-dash free.
+module IndexEntry
+  module_function
+
+  EM_DASH = "\u2014".freeze
+  ENTRY_RE = /\A- \[(\S+)\s+(?:#{Regexp.escape(EM_DASH)}|-)\s+(.*?)\]\(([^)]+)\)/.freeze
+
+  # Match `line` (already chomped) against the shared INDEX entry shape.
+  # Returns a MatchData (captures: 1 = id, 2 = title, 3 = link) or nil.
+  def match(line)
+    line.to_s.match(ENTRY_RE)
+  end
+
+  # True iff the intent is Active in its store's INDEX.md, which lives at the
+  # PARENT of the store/ dir. Non-raising: any failure (missing or unreadable
+  # INDEX, bad arg) returns false. `index_active_ids` is a pure-data test
+  # seam: when an Array of id strings is supplied, membership is checked
+  # against it directly with no file read.
+  def active?(intent_id, store:, index_active_ids: nil)
+    target = intent_id.to_s
+    return index_active_ids.include?(target) if index_active_ids.is_a?(Array)
+
+    index = File.join(File.dirname(store.to_s), "INDEX.md")
+    return false unless File.exist?(index)
+
+    in_active = false
+    File.foreach(index) do |line|
+      stripped = line.chomp
+      if stripped == "## Active"
+        in_active = true
+        next
+      end
+      next unless in_active
+      break if stripped.start_with?("## ") # next section ends the Active block
+      m = match(stripped)
+      return true if m && m[1] == target
+    end
+    false
+  rescue StandardError
+    false
+  end
+end

package/scripts/lib/insights.rb

@@ -2,7 +2,7 @@
 # encoding: UTF-8
 
 # insights.rb - the blessed write path for an intent's `## Insights` section
-# (intent 82). A sibling library to bridge.rb so the insight write path stays
+# (intent 82). A standalone library so the insight write path stays
 # independent of the savepoint ledger (the spec forbids touching the ledger).
 #
 # Every entry leads with a fixed, machine-parseable prefix

package/scripts/lib/installer_core.rb

@@ -6,6 +6,7 @@ require "yaml"
 require "fileutils"
 require "digest"
 require "time"
+require "tmpdir"
 require_relative "hook_registry"
 require_relative "agent_models"
 require_relative "harness_text"
@@ -254,7 +255,10 @@ class InstallerCore
 
   # --- Distribution phase ---
 
-  def distribute(mode)
+  # `tmp_dirs:` defaults to the real system tmp directory plus `/tmp` (where a
+  # retired session-state leftover would sit); a test overrides it (often to
+  # `[]`) so the removal never scans the real filesystem's tmp directories.
+  def distribute(mode, tmp_dirs: [Dir.tmpdir, "/tmp"].uniq)
     puts "  \u{1f4e6} #{mode == :update ? "Updating" : "Installing"} core files to #{plastic_home}"
 
     manifest_path = File.join(plastic_home, "manifest.json")
@@ -296,6 +300,8 @@ class InstallerCore
     write_manifest(global_files, manifest_path)
 
     pruned = prune_removed_files(old_files - global_files, root: plastic_home)
+    removed = remove_retired_session_state(plastic_home: plastic_home, tmp_dirs: tmp_dirs)
+    puts "  \u{1f9f9} #{removed} retired session state file(s) removed" if removed.positive?
 
     puts "  \u{2705} Core files synced (v#{version})#{pruned.positive? ? ", #{pruned} stale file(s) pruned" : ""}"
   end
@@ -372,10 +378,12 @@ class InstallerCore
       "scripts/lib/agent_models.rb" => "scripts/lib/agent_models.rb",
       "scripts/lib/config_asks.rb" => "scripts/lib/config_asks.rb",
       "scripts/lib/release_guard.rb" => "scripts/lib/release_guard.rb",
-      "scripts/lib/bridge.rb" => "scripts/lib/bridge.rb",
+      "scripts/lib/index_entry.rb" => "scripts/lib/index_entry.rb",
+      "scripts/lib/project_config.rb" => "scripts/lib/project_config.rb",
       "scripts/lib/savepoint.rb" => "scripts/lib/savepoint.rb",
       "scripts/lib/guarded_append.rb" => "scripts/lib/guarded_append.rb",
       "scripts/lib/node_ledger.rb" => "scripts/lib/node_ledger.rb",
+      "scripts/lib/node_input_compatibility.rb" => "scripts/lib/node_input_compatibility.rb",
       "scripts/lib/node_progress.rb" => "scripts/lib/node_progress.rb",
       "scripts/node-transition" => "scripts/node-transition",
       "scripts/lib/arm.rb" => "scripts/lib/arm.rb",
@@ -513,11 +521,11 @@ class InstallerCore
       "scripts/lib/roadmap_migration.rb" => "scripts/lib/roadmap_migration.rb",
       "scripts/roadmap-graph" => "scripts/roadmap-graph",
       "scripts/index-projection" => "scripts/index-projection",
-      # Intent 338 (G5): the node packet command - the trust-boundary wrapper,
+      # Intent 338 (G5): the node input command - the trust-boundary wrapper,
       # the five-block gatherer/assembler, and the CLI 340's runner calls.
-      "scripts/lib/packet_wrapper.rb" => "scripts/lib/packet_wrapper.rb",
-      "scripts/lib/node_packet.rb" => "scripts/lib/node_packet.rb",
-      "scripts/node-packet" => "scripts/node-packet",
+      "scripts/lib/data_boundary.rb" => "scripts/lib/data_boundary.rb",
+      "scripts/lib/node_input.rb" => "scripts/lib/node_input.rb",
+      "scripts/node-input" => "scripts/node-input",
       # Intent 342 (G9): the backward shim that presents actions/*.md as a
       # node graph for any legacy intent, so WorkGraphValidator can require
       # it without going red on contact with install_sync_test.
@@ -593,7 +601,7 @@ class InstallerCore
       "scripts/lib/graph_measure_report.rb" => "scripts/lib/graph_measure_report.rb",
       # Intent 343 (G10, n4): the `budget` verb - whether the `budget:` a
       # node's envelope declares (327 C19) is a ceiling that ever actually
-      # held, read from the ledger and the real packet files.
+      # held, read from the ledger and the real input files.
       "scripts/lib/graph_measure_budget.rb" => "scripts/lib/graph_measure_budget.rb",
       # Intent 343 (G10, n5): the `cohorts` verb's model section - the store
       # walk and whether a recorded model= still matches what config
@@ -885,6 +893,111 @@ class InstallerCore
     removed
   end
 
+  # Intent 344 (G11, D10): leftovers from the retired per-session day pointer
+  # and the retired inter-hook coordination key. A `current` candidate is
+  # real only when reached with no symlink between plastic_home and the
+  # session directory: a store root's own real path must equal the plain
+  # join of plastic_home's real path with the store's lexical relative path
+  # (a symlinked store, or a symlinked projects/<slug> above it, breaks
+  # that equality), and neither the store's `.tmp` directory nor the
+  # session directory beneath it may itself be a symlink. A tmp-file
+  # candidate is judged by its containing directory's real path instead,
+  # so a symlinked tmp root such as macOS's real /tmp still works; its
+  # name is matched on raw bytes so an undecodable name never raises.
+  # Never opens or parses a candidate: a torn or malformed leftover is
+  # deleted by name alone, exactly like a well-formed one. Only a regular
+  # file that is not a symlink is ever a candidate for deletion. Returns
+  # the count removed; a delete failure warns once per path and the sync
+  # continues, since a stuck leftover must never fail an install.
+  def remove_retired_session_state(plastic_home:, tmp_dirs:)
+    candidates = []
+
+    real_store_roots(plastic_home).each do |store_root|
+      candidates.concat(current_candidates(store_root))
+    end
+
+    Array(tmp_dirs).compact.each do |dir|
+      candidates.concat(tmp_json_candidates(dir))
+    end
+
+    removed = 0
+    candidates.uniq.each do |candidate|
+      begin
+        next unless File.lstat(candidate).file?
+      rescue SystemCallError
+        next
+      end
+
+      begin
+        File.delete(candidate)
+        removed += 1
+      rescue SystemCallError => e
+        warn "  \u{26a0}\u{fe0f}  Could not remove retired session state #{candidate}: #{e.message}"
+      end
+    end
+    removed
+  rescue StandardError
+    removed || 0
+  end
+
+  # Every store root (the global store, plus each project store) whose real
+  # path is reached with no symlink between it and plastic_home.
+  def real_store_roots(plastic_home)
+    roots = [File.join(plastic_home, "store")] +
+            Dir.glob(File.join(plastic_home, "projects", "*", "store"))
+    roots.select { |root| real_store_root?(plastic_home, root) }
+  end
+
+  def real_store_root?(plastic_home, store_root)
+    return false unless File.directory?(store_root)
+
+    real_home = File.realpath(plastic_home)
+    relative = store_root.sub(/\A#{Regexp.escape(plastic_home)}\/?/, "")
+    File.realpath(store_root) == File.join(real_home, relative)
+  rescue SystemCallError
+    false
+  end
+
+  # `current` candidates under one validated store root: `.tmp` and every
+  # session directory beneath it must be real directories, never symlinks.
+  def current_candidates(store_root)
+    tmp_root = File.join(store_root, ".tmp")
+    return [] unless File.lstat(tmp_root).directory?
+
+    Dir.children(tmp_root).filter_map do |child|
+      begin
+        session_dir = File.join(tmp_root, child)
+        next unless File.lstat(session_dir).directory?
+
+        File.join(session_dir, "current")
+      rescue SystemCallError
+        nil
+      end
+    end
+  rescue SystemCallError
+    []
+  end
+
+  # Retired session-state leftover files sitting directly in `dir`, resolved through
+  # `dir`'s own real path so a symlinked tmp root (macOS's real /tmp) still
+  # works; the name match runs on raw bytes so an undecodable name is
+  # simply not a match, never a raised error.
+  def tmp_json_candidates(dir)
+    real = File.realpath(dir)
+    Dir.children(real).select { |name| retired_tmp_name?(name) }.map { |name| File.join(real, name) }
+  rescue SystemCallError
+    []
+  end
+
+  # True when `name`'s raw bytes match the retired session-state leftover shape
+  # (`plastic-<session>--<id>.json`). Runs on `name.b` so a name that is
+  # not valid UTF-8 is judged on bytes instead of raising.
+  def retired_tmp_name?(name)
+    name.b.match?(/\Aplastic-[^\/]+--[^\/]+\.json\z/n)
+  rescue StandardError
+    false
+  end
+
   # True when `path`, once expanded, is one of `roots` itself or lives underneath
   # one of them. String-prefix containment guarded by a trailing separator so a
   # sibling directory that merely shares a prefix (`/home/x-evil` vs root `/home/x`)

package/scripts/lib/lock.rb

@@ -12,8 +12,8 @@ require "time"
 # savepoint.md (git-ignored, transient state). Ownership is session-keyed (D1):
 # the file records the owner session, never a pid. Liveness is a lease: the
 # owner's hooks touch the file mtime on tool calls (heartbeat); the lock is
-# stale only when that heartbeat is older than the TTL. The /tmp bridge is a
-# per-session CACHE of this state; on any disagreement the lock file wins (D2).
+# stale only when that heartbeat is older than the TTL. This lock file is
+# the sole truth of ownership (D2).
 #
 # Mutual-exclusion seam (D3): the schema carries a type ("delivery" now,
 # "maintenance" in a chained intent after 93) and acquire refuses while the
@@ -27,13 +27,12 @@ module Lock
   # Skill-invocation prefix per harness (intent 201, D2/D3). Claude Code invokes a
   # skill with a slash (/plastic-doctor); Codex CLI invokes explicitly with a
   # dollar ($plastic-doctor) and may also select one implicitly by matching the
-  # skill's description. This table is the actual source of truth for
-  # Bridge.skill_ref (bridge.rb requires lock.rb, never the reverse, so the
-  # table lives here rather than pulling Bridge into this dependency-free file
-  # just to render two characters). InstallerCore::DEFAULT_AGENTS carries the
-  # same values per adapter as documented config (see ACTION_2); this constant
-  # is not read from it at runtime, by the same reasoning bridge.rb/hook-*
-  # already stay clear of installer_core.rb (spec Alternatives Considered).
+  # skill's description. This table is the package-wide source of truth for
+  # `Lock.skill_ref`; every caller reaches it directly rather than duplicating
+  # the prefix table. InstallerCore::DEFAULT_AGENTS carries the same values per
+  # adapter as documented config (see ACTION_2); this constant is not read from
+  # it at runtime, by the same reasoning this file and hook-* already stay
+  # clear of installer_core.rb (spec Alternatives Considered).
   SKILL_PREFIXES = { "claude" => "/", "codex" => "$" }.freeze
 
   # Renders a skill reference for the given harness. Unset or unrecognized