@zalom/plastic 2.0.0-alpha.1 → 2.0.0-alpha.3

package/scripts/lib/installer_core.rb

@@ -9,6 +9,7 @@ require "time"
 require_relative "hook_registry"
 require_relative "agent_models"
 require_relative "harness_text"
+require_relative "compact_instructions"
 
 # Shared installer machinery, instantiable with injected package root / store / agent
 # map so the verb scripts (install/update/uninstall/rollback) and their tests can run
@@ -33,6 +34,15 @@ class InstallerCore
   # Regex matching exactly one managed section (BEGIN line .. END line), non-greedy.
   CODEX_SECTION_RE = /^<!-- BEGIN PLASTIC INTEGRATION.*?-->\n.*?\n<!-- END PLASTIC INTEGRATION -->\n?/m
 
+  # Claude CLAUDE.md marked-section markers (intent 312). A pair of its own, not the
+  # Codex literals: the two managed files can be one file (a user who symlinks
+  # ~/.claude/CLAUDE.md at ~/.codex/AGENTS.md, or the reverse), and a shared literal
+  # would let one body silently replace the other and an uninstall of one strip both.
+  # doctor_core.rb matches these literals structurally, so keep the two in sync by hand.
+  CLAUDE_SECTION_BEGIN_PREFIX = "<!-- BEGIN PLASTIC COMPACT"
+  CLAUDE_SECTION_END = "<!-- END PLASTIC COMPACT -->"
+  CLAUDE_SECTION_RE = /^<!-- BEGIN PLASTIC COMPACT.*?-->\n.*?\n<!-- END PLASTIC COMPACT -->\n?/m
+
   # Curated essentials plus a pointer to ~/.plastic/PLASTIC.md and the plastic-conventions
   # skill, injected into ~/.codex/AGENTS.md. Not a slice of PLASTIC.md itself: AGENTS.md is
   # a shared file Codex merges from multiple sources, so this block stays a small,
@@ -336,6 +346,7 @@ class InstallerCore
       "scripts/lib/lock.rb" => "scripts/lib/lock.rb",
       "scripts/plastic-lock" => "scripts/plastic-lock",
       "scripts/lib/hook_registry.rb" => "scripts/lib/hook_registry.rb",
+      "scripts/lib/compact_instructions.rb" => "scripts/lib/compact_instructions.rb",
       "scripts/agent-report" => "scripts/agent-report",
       "scripts/lib/insights.rb" => "scripts/lib/insights.rb",
       "scripts/insight-append" => "scripts/insight-append",
@@ -408,6 +419,11 @@ class InstallerCore
       "scripts/lib/session_backfill.rb" => "scripts/lib/session_backfill.rb",
       "scripts/lib/session_close.rb" => "scripts/lib/session_close.rb",
       "scripts/lib/session_git.rb" => "scripts/lib/session_git.rb",
+      "scripts/lib/handoff.rb" => "scripts/lib/handoff.rb",
+      "scripts/lib/day_summary.rb" => "scripts/lib/day_summary.rb",
+      "scripts/write-handoff" => "scripts/write-handoff",
+      "scripts/day-summary" => "scripts/day-summary",
+      "scripts/hook-savepoint" => "scripts/hook-savepoint",
     }
   end
 
@@ -421,6 +437,8 @@ class InstallerCore
       version: 3
       execution_mode: subagent-driven
       stale_threshold_days: 3
+      context_offer_tokens: 350000
+      context_insist_tokens: 500000
       hash_length: 6
       hash_algorithm: sha256-base36
       max_slug_words: 5
@@ -779,6 +797,11 @@ class InstallerCore
     choice = statusline_choice(settings_path, argv: argv, input: input, reinstall: reinstall)
     merge_claude_hooks(settings_path, choice: choice)
 
+    # Instruction injection (intent 312): the compact-instructions block into
+    # ~/.claude/CLAUDE.md. A partial-ownership user file, so it is NOT manifest-tracked
+    # (stripped surgically on uninstall), the same treatment ~/.codex/AGENTS.md gets.
+    inject_claude_compact_md(File.join(config[:dir], "CLAUDE.md"))
+
     # Write manifest
     manifest_path = File.join(plastic_dir, "manifest.json")
     write_manifest(installed, manifest_path)
@@ -1344,14 +1367,28 @@ class InstallerCore
     raise e
   end
 
-  def codex_section(body: CODEX_AGENTS_MD_BODY)
+  # A managed instruction file may be a symlink into a dotfiles repo. write_text_atomic
+  # renames a temp file over its argument, which would replace the link with a regular
+  # file and silently detach it, so every read and write resolves the link first and the
+  # change lands on its target (intent 312).
+  def resolve_managed_path(path)
+    File.symlink?(path) ? File.realpath(path) : path
+  rescue Errno::ENOENT
+    path
+  end
+
+  def marked_section(body: CODEX_AGENTS_MD_BODY, begin_prefix: CODEX_SECTION_BEGIN_PREFIX,
+                     end_marker: CODEX_SECTION_END)
     hash = Digest::SHA256.hexdigest(body)[0, 12]
-    "#{CODEX_SECTION_BEGIN_PREFIX} hash:#{hash} -->\n#{body.strip}\n#{CODEX_SECTION_END}\n"
+    "#{begin_prefix} hash:#{hash} -->\n#{body.strip}\n#{end_marker}\n"
   end
 
   # Returns :created / :appended / :replaced / :refused. Never raises on a normal user file.
-  def inject_codex_agents_md(path, body: CODEX_AGENTS_MD_BODY)
-    section = codex_section(body: body)
+  def inject_marked_section(path, body: CODEX_AGENTS_MD_BODY,
+                            begin_prefix: CODEX_SECTION_BEGIN_PREFIX,
+                            end_marker: CODEX_SECTION_END, section_re: CODEX_SECTION_RE)
+    section = marked_section(body: body, begin_prefix: begin_prefix, end_marker: end_marker)
+    path = resolve_managed_path(path)
 
     unless File.exist?(path)
       FileUtils.mkdir_p(File.dirname(path))
@@ -1360,14 +1397,14 @@ class InstallerCore
     end
 
     content = File.read(path)
-    has_begin = content.include?(CODEX_SECTION_BEGIN_PREFIX)
-    has_end = content.include?(CODEX_SECTION_END)
+    has_begin = content.include?(begin_prefix)
+    has_end = content.include?(end_marker)
 
     # 22a safety rule: never write if the existing section cannot be parsed.
     return :refused if has_begin && !has_end
 
     if has_begin
-      write_text_atomic(path, content.sub(CODEX_SECTION_RE, section))
+      write_text_atomic(path, content.sub(section_re, section))
       :replaced
     else
       base = content.end_with?("\n") ? content : content + "\n"
@@ -1376,18 +1413,41 @@ class InstallerCore
     end
   end
 
+  # --- The two blocks Plastic ships, each with its own marker pair ---
+
+  def codex_section(body: CODEX_AGENTS_MD_BODY)
+    marked_section(body: body)
+  end
+
+  def inject_codex_agents_md(path, body: CODEX_AGENTS_MD_BODY)
+    inject_marked_section(path, body: body)
+  end
+
+  # The compact-instructions block for ~/.claude/CLAUDE.md (intent 312).
+  def claude_compact_section(body: CompactInstructions::BODY)
+    marked_section(body: body, begin_prefix: CLAUDE_SECTION_BEGIN_PREFIX,
+                   end_marker: CLAUDE_SECTION_END)
+  end
+
+  def inject_claude_compact_md(path, body: CompactInstructions::BODY)
+    inject_marked_section(path, body: body, begin_prefix: CLAUDE_SECTION_BEGIN_PREFIX,
+                          end_marker: CLAUDE_SECTION_END, section_re: CLAUDE_SECTION_RE)
+  end
+
   # Remove exactly Plastic's managed section from a user-owned AGENTS.md. Preserve all other
   # content. Delete the file only if Plastic created it and nothing else remains. Returns the
   # path when it acted, nil on no-op. Mirrors remove_claude_hooks: dedicated surgical strip,
   # never the manifest whole-file-delete path.
-  def strip_codex_section(path)
+  def strip_marked_section(path, begin_prefix: CODEX_SECTION_BEGIN_PREFIX,
+                           section_re: CODEX_SECTION_RE)
+    path = resolve_managed_path(path)
     return nil unless File.exist?(path)
     content = File.read(path)
-    return nil unless content.include?(CODEX_SECTION_BEGIN_PREFIX)
+    return nil unless content.include?(begin_prefix)
 
     # Remove the section plus the single separator newline the append introduced, so a
     # standard user file round-trips byte-identical.
-    stripped = content.sub(/\n?#{CODEX_SECTION_RE}/, "")
+    stripped = content.sub(/\n?#{section_re}/, "")
 
     if stripped.strip.empty?
       File.delete(path)                 # Plastic-created file: nothing else left
@@ -1398,6 +1458,15 @@ class InstallerCore
     path
   end
 
+  def strip_codex_section(path)
+    strip_marked_section(path)
+  end
+
+  def strip_claude_compact_section(path)
+    strip_marked_section(path, begin_prefix: CLAUDE_SECTION_BEGIN_PREFIX,
+                         section_re: CLAUDE_SECTION_RE)
+  end
+
   # --- Uninstall ---
 
   def handle_uninstall(uninstall_agents)
@@ -1424,6 +1493,7 @@ class InstallerCore
     puts "     ls ~/.claude/skills | grep '^plastic-'      # → no output"
     puts "     ls ~/.claude/hooks | grep '^plastic-'       # → no output"
     puts "     grep -c plastic ~/.claude/settings.json     # → only hook refs gone"
+    puts "     grep 'PLASTIC COMPACT' ~/.claude/CLAUDE.md  # → no output"
     puts "\n  To also delete your intent store: rm -rf #{tilde(plastic_home)}\n\n"
   end
 
@@ -1470,6 +1540,11 @@ class InstallerCore
       settings_path = File.join(config[:dir], "settings.json")
       remove_claude_hooks(settings_path) if File.exist?(settings_path)
       removed.concat(migrate_legacy_plugin(config[:dir]))
+
+      # The compact-instructions block in the user-owned CLAUDE.md (intent 312): a
+      # surgical strip, never the manifest whole-file-delete path above.
+      stripped = strip_claude_compact_section(File.join(config[:dir], "CLAUDE.md"))
+      removed << stripped if stripped
     end
 
     # Codex: surgically strip Plastic's marked section from the user-owned AGENTS.md

package/scripts/lib/session_close.rb

@@ -9,12 +9,22 @@
 
 require "fileutils"
 require_relative "session_ledger"
+require_relative "handoff"
 
 module SessionClose
   module_function
 
   NOOP_REASONS = %w[clear resume].freeze
 
+  # The default hand-off writer (intent 311, spec D6): renders this session's
+  # share of the pointer day into handoff--<session>.md before the tmp dir
+  # goes. The hook script builds it with the shipped templates dir.
+  def default_handoff(templates)
+    lambda do |store, day, session|
+      Handoff.write(store: store, day: day, session: session, trigger: "close", templates: templates)
+    end
+  end
+
   # The default spawner starts the day filer detached so a slow filing never
   # blocks the harness shutdown (Codex kills a SessionEnd hook after 3 s).
   def default_spawner(script)
@@ -26,8 +36,8 @@ module SessionClose
   end
 
   # Returns a small report hash; never raises.
-  def run(payload:, store:, today:, spawner:, now: Time.now)
-    report = { reason: nil, dropped: 0, removed_tmp: false, spawned: nil }
+  def run(payload:, store:, today:, spawner:, handoff: nil, now: Time.now)
+    report = { reason: nil, dropped: 0, removed_tmp: false, spawned: nil, handoff: false }
     reason = payload.is_a?(Hash) ? payload["reason"].to_s : ""
     report[:reason] = reason
     return report if NOOP_REASONS.include?(reason)
@@ -49,6 +59,16 @@ module SessionClose
       count
     end || 0
 
+    # The hand-off (intent 311, spec D6) is written after the drop, so it
+    # reflects it, and before the tmp dir goes, since the pointer lives there.
+    # An intent pointer falls back to today, the same as the drop above.
+    if handoff
+      report[:handoff] = safely do
+        handoff.call(store, pointer_day, session)
+        true
+      end || false
+    end
+
     report[:removed_tmp] = safely do
       dir = SessionLedger.session_tmp_dir(store, session)
       FileUtils.rm_rf(dir) if Dir.exist?(dir)

package/scripts/read-config

@@ -14,6 +14,9 @@ require_relative "lib/agent_models"
 DEFAULTS = {
   "version" => 3,
   "stale_threshold_days" => 3,
+  # Absolute token counts for a 1M window, 35 and 50 percent (intent 312, 296 D38).
+  "context_offer_tokens" => 350_000,
+  "context_insist_tokens" => 500_000,
   "execution_mode" => "subagent-driven",
   "hash_length" => 6,
   "hash_algorithm" => "sha256-base36",

package/scripts/rollback.rb

@@ -118,6 +118,12 @@ class Rollback < InstallerCore
           remove_claude_hooks(path)
           stripped << path
         end
+        # The compact-instructions block (intent 312), for the same reason: no older
+        # package knows the section exists, so nothing there would ever replace or
+        # remove it. The Codex AGENTS.md section needs no equivalent: every older
+        # package knows that one and rewrites it on the downgrade install.
+        claude_md = strip_claude_compact_section(File.join(agent[:dir], "CLAUDE.md"))
+        stripped << claude_md if claude_md
       when "codex"
         path = agent[:home_dir] && File.join(agent[:home_dir], "hooks.json")
         if path && File.exist?(path)

package/scripts/write-handoff

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# write-handoff (intent 311): render and write one session's hand-off into
+# the day directory (.sessions/<day>/handoff--<session>.md). Derived from the
+# day ledger, so it can be regenerated at any time. Prints the path.
+#
+# Usage:
+#   write-handoff --trigger tick|precompact|close [--store <dir>] [--day <YYYYMMDD>]
+#                 [--session <id>] [--templates <dir>]
+#
+# Defaults match append-ledger: the store is $PLASTIC_HOME/store, the day is
+# today (local wall clock), the session is $CLAUDE_CODE_SESSION_ID, and the
+# templates dir is the one shipped next to this script.
+#
+# Exit codes: 0 done; 2 usage error.
+
+require_relative "lib/session_ledger"
+require_relative "lib/handoff"
+
+def usage_abort(message)
+  warn "write-handoff: #{message}"
+  exit 2
+end
+
+def expand(path)
+  File.expand_path(path.to_s.sub(/\A~/, Dir.home))
+end
+
+def parse_args(argv)
+  opts = {}
+  i = 0
+  while i < argv.length
+    flag = argv[i]
+    usage_abort("unknown argument #{flag.inspect}") unless flag.start_with?("--")
+    usage_abort("#{flag} requires a value") if i + 1 >= argv.length
+    key = flag.delete_prefix("--").to_sym
+    usage_abort("unknown flag #{flag.inspect}") unless %i[store day session trigger templates].include?(key)
+    opts[key] = argv[i + 1]
+    i += 2
+  end
+  opts
+end
+
+opts = parse_args(ARGV)
+usage_abort("--trigger is required (#{Handoff::TRIGGERS.join(', ')})") unless opts[:trigger]
+usage_abort("--trigger must be one of #{Handoff::TRIGGERS.join(', ')}") unless Handoff::TRIGGERS.include?(opts[:trigger])
+
+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]) : File.expand_path("../templates", __dir__)
+usage_abort("templates dir not found: #{templates}") unless Dir.exist?(templates)
+
+day = opts[:day] || SessionLedger.day_id
+usage_abort("--day must be eight digits parsing as a real date, got #{day.inspect}") unless SessionLedger.valid_day_id?(day)
+session = SessionLedger.short_session_id(opts[:session], ENV["CLAUDE_CODE_SESSION_ID"])
+
+puts Handoff.write(store: store, day: day, session: session, trigger: opts[:trigger], templates: templates)
+exit 0

package/skills/intent-continuing/SKILL.md

@@ -95,8 +95,9 @@ For a live intent's directory:
    ```bash
    ruby -r ~/.plastic/scripts/lib/savepoint -e 'Savepoint.rebuild_savepoint("<intent_dir>")'
    ```
-3. **Read the hand-off.** When `resources/handoff--*.md` exists, its newest file is the prior
-   session's own account of where things stand; read it after the ledger, never instead of it.
+3. **Read the hand-off.** The newest `~/.plastic/store/.sessions/<day>/handoff--*.md` (today,
+   else the newest prior day) is the prior session's own account of where things stand; read
+   it after the ledger, never instead of it.
 4. **Derive the next step:** the first unchecked item in `checklist.md` when it exists, else
    the next thing the station needs (see the matrix). The newest `## Insights` entry supplies
    the human-readable context; an entry marked `(autonomous)` means an auto team was

package/templates/config.yml

@@ -2,6 +2,11 @@ version: 3
 project_roots:
   - ~/.plastic/projects
 stale_threshold_days: 3
+# When to compact. Absolute token counts for a 1M window (35 and 50 percent), not
+# percentages: models are reliable only to roughly 50 to 65 percent of advertised
+# context, so a percentage that is right at 200k floats to an untested size at 1M.
+context_offer_tokens: 350000
+context_insist_tokens: 500000
 execution_mode: subagent-driven
 hash_length: 6
 hash_algorithm: sha256-base36