rubik 0.1.0

data/lib/rubik/prompt/context_compactor.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+require_relative "token_estimator"
+require_relative "conversation_rows"
+require_relative "../tools/truncator"
+
+module Rubik
+  module Prompt
+    module ContextCompactor
+      # Plan 61 D-12: single source of truth for the live conversation
+      # window cap (TurnRecorder and Session::Manager both use it).
+      DEFAULT_MAX_CONVERSATION_ENTRIES = 40
+
+      module_function
+
+      def effective_input_ceiling(context_limit:, max_output_tokens: 4096, safety_margin: 1024)
+        [1024, context_limit.to_i - max_output_tokens.to_i - safety_margin.to_i].max
+      end
+
+      def needs_compaction?(history, context_limit:, max_output_tokens: 4096, safety_margin: 1024, max_tokens_ratio: 0.85, config: {})
+        return false if history.nil? || history.empty?
+
+        ratio = (config["max_tokens_ratio"] || config[:max_tokens_ratio] || max_tokens_ratio || 0.85).to_f
+        margin = (config["safety_margin_tokens"] || config[:safety_margin_tokens] || safety_margin || 1024).to_i
+        max_out = (config["max_output_tokens"] || config[:max_output_tokens] || max_output_tokens || 4096).to_i
+
+        ceiling = effective_input_ceiling(
+          context_limit: context_limit,
+          max_output_tokens: max_out,
+          safety_margin: margin
+        )
+        threshold = (ceiling * ratio).to_i
+        total_tokens = TokenEstimator.estimate_history(history)
+        total_tokens > threshold
+      end
+
+      # absorb: (goal-ledger planı D) duck-typed directive — nil (default)
+      # iken tier atlanır ve davranış bit-bit aynıdır; verilirse dup
+      # kopyaya #apply!(rows) uygulanır (prompt katmanı goal bilmez;
+      # directive'i orchestrator/goal_ledger ailesi kurar).
+      def compact_history(history, context_limit:, max_output_tokens: 4096, safety_margin: 1024, config: {}, force: false, absorb: nil)
+        return [] if history.nil? || history.empty?
+
+        strategy = (config["compaction_strategy"] || config[:compaction_strategy] || "hybrid").to_s
+        return history.map { |m| ConversationRows.row?(m) ? m.dup : m } if strategy == "off"
+
+        max_tokens_ratio = (config["max_tokens_ratio"] || config[:max_tokens_ratio] || 0.85).to_f
+        tool_result_prune_chars = (config["tool_result_prune_chars"] || config[:tool_result_prune_chars] || 1500).to_i
+        preserve_first_n = (config["preserve_first_n"] || config[:preserve_first_n] || 2).to_i
+        preserve_last_n = (config["preserve_last_n"] || config[:preserve_last_n] || 6).to_i
+        safety_margin = (config["safety_margin_tokens"] || config[:safety_margin_tokens] || safety_margin || 1024).to_i
+
+        ceiling = effective_input_ceiling(
+          context_limit: context_limit,
+          max_output_tokens: max_output_tokens,
+          safety_margin: safety_margin
+        )
+        threshold = (ceiling * max_tokens_ratio).to_i
+
+        # Return duplicate if under threshold and not forced
+        if !force && TokenEstimator.estimate_history(history) <= threshold
+          return history.map { |m| ConversationRows.row?(m) ? m.dup : m }
+        end
+
+        compacted = history.map { |m| ConversationRows.row?(m) ? m.dup : m }
+
+        # Tier 0 (plan D): absorption — generic drop'lardan ÖNCE; absorb
+        # tek başına eşiği karşıladıysa (force yoksa) generic tier'lar hiç
+        # koşmaz (:72 erken-çıkış kalıbının aynası).
+        if absorb
+          absorb.apply!(compacted)
+          return compacted if !force && TokenEstimator.estimate_history(compacted) <= threshold
+        end
+
+        # Strategy: prune_tool_results or hybrid (Phase 1: Pruning intermediate tool results)
+        if ["hybrid", "prune_tool_results"].include?(strategy)
+          compacted = prune_intermediate_tool_results(
+            compacted,
+            preserve_first_n: preserve_first_n,
+            preserve_last_n: preserve_last_n,
+            max_chars: tool_result_prune_chars
+          )
+
+          return compacted if strategy == "prune_tool_results" || (!force && TokenEstimator.estimate_history(compacted) <= threshold)
+        end
+
+        # Strategy: sliding_window or hybrid (Phase 2: Collapsing intermediate atomic units)
+        if ["hybrid", "sliding_window"].include?(strategy)
+          compacted = apply_sliding_window(
+            compacted,
+            threshold: threshold,
+            preserve_first_n: preserve_first_n,
+            preserve_last_n: preserve_last_n,
+            force: force
+          )
+        end
+
+        compacted
+      end
+
+      def prune_intermediate_tool_results(history, preserve_first_n:, preserve_last_n:, max_chars:)
+        return history if history.size <= preserve_first_n + preserve_last_n
+
+        first_end_idx = preserve_first_n
+        last_start_idx = [history.size - preserve_last_n, first_end_idx].max
+
+        history.each_with_index do |msg, idx|
+          next unless idx >= first_end_idx && idx < last_start_idx
+          next unless ConversationRows.row?(msg)
+
+          role = ConversationRows.role_of(msg)
+          next unless ["tool", "tool_result"].include?(role)
+
+          # A loaded skill body is the task's standing instruction payload
+          # (progressive disclosure), not intermediate output — pruning it to
+          # max_chars mid-task would silently amputate the agent's orders.
+          # The sliding-window phase may still drop it under genuine token
+          # emergency; the <skills> index lets the agent re-invoke `skill`.
+          next if (msg[:tool_name] || msg["tool_name"]) == Rubik::Tools::SkillTool::NAME
+
+          content_key = ConversationRows.content_key_of(msg)
+          content = msg[content_key].to_s
+          if content.length > max_chars
+            trunc = Rubik::Tools::Truncator.truncate(content, max_chars: max_chars, strategy: :head_tail)
+            msg[content_key] = trunc[:text]
+          end
+        end
+
+        history
+      end
+
+      def group_atomic_units(history)
+        units = []
+        i = 0
+        while i < history.size
+          msg = history[i]
+          role = ConversationRows.role_of(msg)
+          tool_calls = msg[:tool_calls] || msg["tool_calls"]
+
+          if role == "assistant" && tool_calls && !tool_calls.empty?
+            unit = [msg]
+            j = i + 1
+            while j < history.size
+              next_msg = history[j]
+              next_role = ConversationRows.role_of(next_msg)
+              break unless ["tool", "tool_result"].include?(next_role)
+
+              unit << next_msg
+              j += 1
+
+            end
+            units << unit
+            i = j
+          else
+            units << [msg]
+            i += 1
+          end
+        end
+        units
+      end
+
+      # Hedef mesajı mı? <user_task> sarmalayıcısını yalnızca
+      # ContextBuilder.format_user_task üretir — goal/plan döngülerinin görev
+      # bildirgesi. Açılış+kapanış etiketi birlikte aranır: kullanıcı
+      # mesajına alıntılanmış yalnızca açılış etiketi yapıştırmak mesajı
+      # kalıcı olarak sabitleyip düşürülemez/devrilinemez hale getirirdi.
+      # String/symbol anahtar farkı umursanmaz.
+      def goal_message?(msg)
+        return false unless ConversationRows.row?(msg)
+
+        role = ConversationRows.role_of(msg)
+        content = ConversationRows.content_of(msg).to_s
+        role == "user" && content.include?("<user_task>") && content.include?("</user_task>")
+      end
+
+      # Yapılandırılmış goal ledger satırı mı? (goal-ledger planı A) —
+      # goal_message? ile aynı alıntı-tek-etiket disiplini: açılış
+      # `<goal_ledger ` + kapanış `</goal_ledger>` BİRLİKTE aranır; kullanıcı
+      # mesajına yapıştırılan tek etiket mesajı pınleyemez. Role "user"
+      # zorunludur (EmergencyCompactor hard tier user satırlarına dokunmaz).
+      def ledger_message?(msg)
+        return false unless ConversationRows.row?(msg)
+
+        role = ConversationRows.role_of(msg)
+        content = ConversationRows.content_of(msg).to_s
+        role == "user" && content.start_with?("<goal_ledger ") && content.include?("</goal_ledger>")
+      end
+
+      # İsim korunur (pruner rules.rb:39 çağrısı yük taşıyor): pin ailesi
+      # artık hedef satırı VE güncel Σ satırını kapsar.
+      def unit_pins_goal?(unit)
+        unit.any? { |msg| goal_message?(msg) || ledger_message?(msg) }
+      end
+
+      def apply_sliding_window(history, threshold:, preserve_first_n:, preserve_last_n:, force: false) # rubocop:disable Lint/UnusedMethodArgument -- arayüz uyumluluğu için force korunuyor
+        units = group_atomic_units(history)
+        return history if units.size <= 2
+
+        # Hedef sabitleme: <user_task> taşıyan birimler ARA birim olsa bile
+        # asla düşürülemez ve trim edilemez — model hedefini koşu ortasında
+        # kaybetmesin. Normal ve emergency yolların ikisi de compact_history
+        # üzerinden buraya akar. Birden çok <user_task> (run yeniden girişi)
+        # özgün sırasıyla sabitlenir.
+        pinned = units.map { |unit| unit_pins_goal?(unit) }
+
+        # Determine head units (covering at least preserve_first_n messages)
+        head_units = []
+        head_msg_count = 0
+        head_idx = 0
+        while head_idx < units.size && head_msg_count < preserve_first_n
+          head_units << units[head_idx]
+          head_msg_count += units[head_idx].size
+          head_idx += 1
+        end
+
+        # Determine tail units (covering at least preserve_last_n messages)
+        tail_units = []
+        tail_msg_count = 0
+        tail_idx = units.size - 1
+        while tail_idx >= head_idx && tail_msg_count < preserve_last_n
+          tail_units.unshift(units[tail_idx])
+          tail_msg_count += units[tail_idx].size
+          tail_idx -= 1
+        end
+
+        intermediate_indexes = (head_idx..tail_idx).to_a
+        return history if intermediate_indexes.empty?
+
+        # Sabitlenmiş birimler düşürülemeyeceğinden droppable kuyruğundan
+        # çıkarılır; yalnızca kalanlar (en eskiden yeniye) düşürülür.
+        droppable = intermediate_indexes.reject { |idx| pinned[idx] }
+        return history if droppable.empty?
+
+        dropped_indexes = []
+        remaining = droppable.dup
+        # Plan 61 D-9: drop first, THEN measure — the previous loop measured
+        # the candidate before shifting, so it could drop one unit too many.
+        until remaining.empty?
+          dropped_indexes << remaining.shift
+          break if TokenEstimator.estimate_history(assemble_window(units, dropped_indexes)) <= threshold
+        end
+
+        result = assemble_window(units, dropped_indexes)
+
+        # Unit dropping cannot shrink a single oversized user turn —
+        # hard-trim the largest remaining plain messages if still over.
+        # Sabitlenmiş aile (hedef <user_task> + Σ <goal_ledger>) bu katmandan muaftır.
+        if TokenEstimator.estimate_history(result) > threshold
+          pinned_indexes = result.each_index.select { |i| goal_message?(result[i]) || ledger_message?(result[i]) }
+          result = trim_oversized_messages(result, threshold: threshold, pinned_indexes: pinned_indexes)
+        end
+        result
+      end
+
+      # Birimleri özgün sıralarında (düşürülenler hariç) birleştirir ve
+      # <compacted_summary>'yi İLK düşürülen birimin konumuna yerleştirir.
+      # Sabitleme yoksa ilk düşürme her zaman ilk ara birimdir → yerleşim,
+      # eski "head + summary + rest" düzeniyle bire bir aynıdır.
+      def assemble_window(units, dropped_indexes)
+        first_drop = dropped_indexes.min
+        result = []
+        summary_slot = nil
+        units.each_with_index do |unit, idx|
+          summary_slot = result.size if idx == first_drop
+          result.concat(unit) unless dropped_indexes.include?(idx)
+        end
+        dropped_msg_count = dropped_indexes.sum { |i| units[i].size }
+        result.insert(summary_slot || result.size, summary_message(dropped_msg_count))
+        result
+      end
+
+      # Plan 61 D-9: last-resort in-place shortening of the largest
+      # user/assistant messages when structural dropping is not enough.
+      # pinned_indexes (hedef <user_task> mesajları) bu katmandan muaftır.
+      def trim_oversized_messages(history, threshold:, min_len: 2000, max_passes: 10, pinned_indexes: [])
+        max_passes.times do
+          break if TokenEstimator.estimate_history(history) <= threshold
+
+          candidates = history.each_index.select { |i| ConversationRows.row?(history[i]) && !pinned_indexes.include?(i) }
+          eligible = candidates.select do |i|
+            role = ConversationRows.role_of(history[i])
+            content = ConversationRows.content_of(history[i])
+            ["user", "assistant"].include?(role) && content.to_s.length > min_len
+          end
+          idx = eligible.max_by { |i| ConversationRows.content_of(history[i]).to_s.length }
+          break if idx.nil?
+
+          content_key = ConversationRows.content_key_of(history[idx])
+          str = history[idx][content_key].to_s
+          trunc = Rubik::Tools::Truncator.truncate(str, max_chars: str.length / 2, max_lines: 10_000, strategy: :head_tail)
+          history[idx][content_key] = trunc[:text]
+        end
+        history
+      end
+
+      # Plan 61 D-12: token-aware rolling window for the long-lived REPL
+      # conversation history. Drops the oldest entries until the estimate
+      # fits the ceiling; max_entries is an absolute cap; the most recent
+      # min_entries messages always survive. The window is guaranteed to
+      # open with a user turn — strict providers (Anthropic) require it.
+      def trim_history_to_budget(history, ceiling:, max_entries: nil, min_entries: 4)
+        return history if history.nil? || history.empty?
+
+        trimmed = history
+        trimmed = trimmed.last(max_entries) if max_entries&.positive? && trimmed.size > max_entries
+
+        limit = ceiling&.positive? ? ceiling : nil
+        trimmed = trimmed.last(trimmed.size - 1) while limit && trimmed.size > min_entries && TokenEstimator.estimate_history(trimmed) > limit
+
+        trimmed = trimmed.last(trimmed.size - 1) while trimmed.size > 1 && ConversationRows.role_of(trimmed.first) != "user"
+        trimmed
+      end
+
+      # Plan 61 D-9: role is "user" (not "system") — strict providers reject
+      # or relocate mid-conversation system messages; the tag text is kept
+      # stable for downstream recognition.
+      def summary_message(dropped_count)
+        {
+          role: "user",
+          content: "<compacted_summary count=\"#{dropped_count}\" " \
+                   "message=\"#{dropped_count} intermediate conversation messages and tool execution steps were collapsed to stay within token limits.\" />"
+        }
+      end
+    end
+  end
+end

data/lib/rubik/prompt/conversation_rows.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Prompt
+    # Single owner of the conversation-row wire dialect (Candidate 7,
+    # arch-deepening 2026-10-08). History rows arrive in two dialects:
+    # symbol-keyed ({ role:, content: } — everything this runtime pushes)
+    # and string-keyed (restored sessions, external providers). Every
+    # probe below is pure; append_notice! is the only mutator (bang =
+    # in-place, explicit per the side-effect policy).
+    module ConversationRows
+      module_function
+
+      # Row guard: nils and non-hash junk rows appear from restored
+      # sessions and test doubles.
+      def row?(row) = row.is_a?(Hash)
+
+      # Raw read in both dialects (no type coercion — callers keep their
+      # own nil/to_s handling).
+      def value_of(row, key) = row[key] || row[key.to_s]
+
+      # Role read, both dialects, stringified (the
+      # `(row[:role] || row["role"]).to_s` idiom of sanitizer/compactors).
+      def role_of(row) = value_of(row, :role).to_s
+
+      # Content read, both dialects. Returns the raw value (may be nil) —
+      # callers keep their own .to_s / length logic.
+      def content_of(row) = value_of(row, :content)
+
+      # Key resolution for WRITES: a row that already carries the symbol
+      # key is written back on the symbol; anything else (string-keyed, or
+      # missing the key entirely) is written on the STRING key. This exact
+      # asymmetry is load-bearing behavior pinned by the merge tests.
+      def resolve_key(row, key)
+        sym = key.to_sym
+        row.key?(sym) ? sym : key.to_s
+      end
+
+      def content_key_of(row) = resolve_key(row, :content)
+
+      # Merge-policy predicate. Deliberately NOT role_of-based: the merge
+      # compares exact string equality (a Symbol :user role must NOT
+      # match), preserving current behavior bit-for-bit.
+      def user_row?(row) = row[:role] == "user" || row["role"] == "user"
+
+      # The notice-merge policy, previously duplicated in
+      # Orchestrator::Loop#merge_notice_block_into_history! and
+      # Lifecycle#inject_subagent_notice_into_conversation_history!.
+      # Mutates history in place and returns it (both current call sites
+      # are statement-position and rely on the in-place mutation).
+      #
+      # Semantics (byte-identical to both originals):
+      # * empty history or non-user trailing row -> push { role: "user",
+      #   content: payload } with SYMBOL keys;
+      # * trailing user row -> append on its existing key dialect:
+      #   "existing\n\npayload"; a row whose content is empty or absent
+      #   gets the payload written directly (absent key resolves to the
+      #   STRING "content" key — see resolve_key).
+      def append_notice!(history, xml_payload)
+        raise ArgumentError, "history must be an Array, got #{history.class}" unless history.is_a?(Array)
+
+        last = history.last
+        if last && user_row?(last)
+          key = content_key_of(last)
+          existing = last[key].to_s
+          last[key] = existing.empty? ? xml_payload : "#{existing}\n\n#{xml_payload}"
+        else
+          history << { role: "user", content: xml_payload }
+        end
+        history
+      end
+    end
+  end
+end

data/lib/rubik/prompt/doctrine.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative "../platform"
+# Vocabulary leaf ONLY, never the orchestrator barrel: orchestrator sits
+# above the prompt layer; this pure platform-only module renders the
+# manage_subagents snippets the rules below teach. Do not widen this edge.
+require_relative "../orchestrator/subagent/notices"
+require_relative "tool_teachings"
+
+module Rubik
+  module Prompt
+    # Doctrine SSOT (architecture review 2026-10-01, candidate 2): ALL
+    # policy prose the prompt teaches — operational rules, role headers,
+    # orchestration guidance, skills preamble, tool wire notes. Owns
+    # WORDING only: rendered data (tool names, schema dumps) arrives as
+    # parameters and services are never touched here (the orchestrator
+    # resolves, the prompt renders). module_function mirrors
+    # ToolTeachings/Notices. Byte-identical rendering is pinned by
+    # test_prompt_golden_output — reword here = fixture diff there, never
+    # a context_builder.rb diff.
+    module Doctrine
+      module_function
+
+      def operational_rules_xml
+        # Maestro doktrini (kullanıcı kararı 2026-10-01): maestro HER modda
+        # orkestratör. Devir caveat'i kural 2-3'ün BAŞINA yazılır — sondaki
+        # ek caveat zayıf modellerde atlanıyordu (opencode-personal bulgusu);
+        # doktrin kendi promptunun içinde çelişmemeli.
+        <<~XML.strip
+          <operational_rules>
+            1. Code Exploration & Review (read-only: shape subagent assignments and answer the user): Use native tools directly (`list_files`, `grep_search`, `search_symbols`, `get_outline`, `read_file`, `find_references`). If neither a tool nor a listed command matches your need, inspect the codebase structurally: examine the directory layout (`list_files`), search for patterns (`grep_search`), read core modules (`get_outline`, `read_file`), and look for TODO/FIXME markers. For conceptual queries (e.g. "code review", "code quality"), do NOT search for the literal words "refactor" or "review"; evaluate the architecture structurally.
+            2. Code Editing & Targeted Changes: MAESTRO OVERRIDE — this rule is delegated wholesale: route ALL edits through 'coder' subagents and never stage edits in your own context (the runtime refuses direct edit tools). The mechanics below are what your coder subagents use. #{Rubik::Prompt::ToolTeachings.teaching_for('replace_file_content')} #{Rubik::Prompt::ToolTeachings.teaching_for('write_file')} #{Rubik::Prompt::ToolTeachings.teaching_for('apply_buffer')}
+            3. Testing & Execution: MAESTRO OVERRIDE — this rule is delegated wholesale: subagents run tests and commands; you read their reports and never execute them yourself (the runtime refuses direct run tools). The mechanics below are what your coder subagents use: they invoke `run_tests` and `run_command` as native tools, never wrapped in `exec_repl_command`. Commands in `run_command` run directly in the project working directory (`<working_directory>`); coder subagents must not prepend `cd` commands or guess non-existent paths (e.g. `/home/ubuntu`). Always fulfill the user's primary requested action (e.g. merge, build, test, commit) to completion. #{Rubik::Prompt::ToolTeachings.teaching_for('run_command')}
+            4. REPL Bang Commands: `exec_repl_command` runs only the session-safe commands listed in <agent_commands> — runtime configuration, context and step-budget self-management, buffer review and rollback, runtime introspection, and code validation. If that section is absent, do not invoke REPL commands. File, code, test, and shell operations never travel through REPL commands — under the maestro doctrine (rules 2-3) they are delegated to subagents, and the direct tools (`read_file`, `write_file`, `replace_file_content`, `run_tests`, `run_command`) are your coder subagents' mechanics. Buffer-review commands (`!diff`, `!undo`, `!rollback`) operate on the in-memory staging buffer (unapplied edits) — they are a preview layer, not file ground truth: verify file content with `read_file`, and read git history from your coder subagent's `run_command` report.
+            5. Autonomous Tool Synthesis: #{Rubik::Prompt::ToolTeachings.teaching_for('synthesize_tool')}
+            6. Output Budget & Conciseness: Respect your output token budget (`<output_budget>`). Produce direct, high-signal responses and avoid unnecessary pleasantries, verbose conversational preambles, or duplicated context blocks that waste generation quota.
+            7. Subagent Delegation & Parallelism (Maestro): As the maestro you orchestrate — ALL execution work (exploration, code changes, verification) is delegated via `invoke_subagent`, in every mode. Match task to archetype: use 'research' for read-only codebase exploration; MUST use 'coder' for code modifications, refactoring, and test execution ('research' has no write or test tools); reach for 'self' (a full capability clone, minus subagent spawning) for work that fits neither archetype — runtime introspection/repair, self-evolution work, hybrid tasks. Subagents execute asynchronously in disposable sub-contexts in the background. After dispatching subagents, do NOT block with 'wait' unless you strictly depend on their output in the current turn — conclude your turn and liberate the prompt so the user can interact concurrently. Completion, budget-pause, error, and message notifications arrive reactively: during your turn via your notification inbox; while you are idle, the runtime automatically wakes you with a dedicated notification-evaluation turn — evaluate the pending notifications, act (extend budget, steer with send_message, retrieve results, wrap up, or report to the user), and conclude your turn again. Subagents can ask YOU questions mid-flight via `ask_question` — a question notification means that subagent is BLOCKED until you reply: answer it promptly with `send_message(recipient: '<id>', message: '<your answer>')` (it times out otherwise). Call `#{Rubik::Orchestrator::Subagent::Notices.wait_hint_template}` only when synchronous waiting is strictly required. Never poll 'status' repeatedly in a loop.
+            8. Runtime Introspection, Self-Healing & Human Feedback: If internal errors or service degradation occur, inspect runtime state with `inspect_runtime` and repair failed services via `repair_runtime_service`. When critical requirements are underspecified or high-impact architectural choices require user confirmation, use `ask_question` with structured multiple-choice options.
+            9. Central Storage & Clean Worktree: #{Rubik::Prompt::ToolTeachings.teaching_for('storage')} #{Rubik::Prompt::ToolTeachings.teaching_for('vakanuvis')} #{Rubik::Prompt::ToolTeachings.teaching_for('show_file')} Subagent transcripts are indexed automatically as `transcript` entities (alias `subagent-<storage-id>`). #{Rubik::Prompt::ToolTeachings.teaching_for('prune_context')}
+          </operational_rules>
+        XML
+      end
+
+      # Returns the UNSTRIPPED mode header; the assembler strips at embed
+      # time (verbatim move from build_system_prompt — rendered bytes are
+      # pinned by the golden fixtures). goal_ledger: goal-mode öğretisi
+      # koşulludur (goal-ledger planı A) — OFF'ta bayt-özdeş; öğreti
+      # TEACHINGS'e giremez (weld testi her öğretiyi operational_rules
+      # içinde zorunlu kılar), goal header'ın 6. maddesinde yaşar.
+      def role_header(mode, goal_ledger: false)
+        case mode.to_sym
+        when :plan
+          <<~HDR
+            You are Rubik (maestro), the orchestrator in PLAN-ONLY mode: you analyze, plan, and orchestrate; execution belongs to subagents.
+            Analyze the user's task within <user_task> and output a concise, numbered step-by-step implementation plan.
+            Do NOT call apply_buffer, write_file, replace_file_content, run_tests, or run_command — the maestro runtime refuses them in every mode; analysis and planning are your work. Proposed changes may sit in the buffer — do not apply them. Specify what files will be created or edited.
+          HDR
+        when :goal
+          ledger_line = " If a `<goal_ledger>` row is present, keep its state current: read `rubik://goal/ledger` and " \
+                        "apply JSON patches with `update_goal_ledger(patch: ...)` against the reported rev after each " \
+                        "meaningful step (task status changes, new findings/decisions)."
+          <<~HDR
+            You are Rubik (maestro), an autonomous AI coding SUPERVISOR in AUTONOMOUS GOAL mode.
+            You own the goal in <user_task> and MUST drive it to verified completion as a pure orchestrator — you conduct, subagents perform. All research, code changes, and verification run in subagent contexts, never in yours:
+            1. Decompose the goal into staged subagent work: at minimum a plan/research stage, a build stage, a review/audit stage whose findings feed a fix stage, and a final verification stage. You decide the exact stages. Declare cross-stage ordering IN THE SAME dispatch with `depends_on` (FS default: the successor launches automatically once the predecessor completes; SS: once it starts) — never fire a stage in parallel with its own predecessors.
+            2. Dispatch every stage with `invoke_subagent`. You MAY explore read-only yourself (`list_files`, `grep_search`, `read_file`) to shape assignments, but ALL code changes and test runs belong to subagents — MUST use the 'coder' archetype for any file modification ('research' is read-only).
+            3. Keep YOUR context lean and managerial: no code drafts, no test output, no full-file reads in your own context — consume stage reports, `rubik://storage/...` summaries, and notification digests instead. Answer subagent `ask_question` prompts promptly.
+            4. Work the notifications, never a poll loop: when subagents are dispatched and nothing needs your immediate action, end your turn WITHOUT calling finish — the runtime waits for them and wakes you with their completion/pause/error/question notices. Ending your turn (or calling finish) with subagents still active does NOT complete the goal: the runtime holds the goal open and re-prompts you with their notices. React to each notice (extend a budget-paused subagent (`manage_subagents` action: 'extend_budget') instead of absorbing its task yourself), then yield again. Conclude with finish ONLY when every dispatched subagent has settled and verification is green.
+            5. Close every stage through verification: read subagent reports, integrate verified results, and run final verification as a subagent stage — a 'coder' mandated to `run_tests` whose green/red report you read. Iterate the review→fix stages until the verifier reports green.
+            6. Live goal snapshot (status, step budget, extensions): read it with `read_file(path: 'rubik://goal/state')`.#{ledger_line if goal_ledger}
+            7. Persist pipeline knowledge in the central storage (`storage` tool): the decomposed plan, review findings, and the final goal record — link stages with entity ids (`links: {"goal": "goal.N.<hash16>"}`) so the audit trail survives the session. Per-stage MEMORY notes go through the chronicler instead: `vakanuvis(action: 'record', topic: '...', body: '...')` mints the `mem.` ref, upserts and supersedes — never write memory with raw storage puts; re-enter prior context with `vakanuvis(action: 'recall', query: '...')` (also after compaction). Keep the repository worktree free of agent workfiles. Transcripts of finished subagents are indexed automatically (searchable via `storage` action 'search') and persist after the subagent is reaped.
+            8. Call `finish` only when the goal is verified, complete, and no dispatched subagent remains active — a premature finish is converted into a wait and you will be re-prompted with their notices. Summarize what each stage produced.
+          HDR
+        else
+          <<~HDR
+            You are Rubik (maestro), a maestro coding orchestrator for the human operator.
+            You ALWAYS work through subagents: research, code changes, and verification run in subagent contexts via `invoke_subagent` (MUST use the 'coder' archetype for any file modification — 'research' is read-only), never in your own context.
+            Keep your own context lean and managerial: you MAY explore read-only (`list_files`, `grep_search`, `read_file`) to understand requests and shape assignments, but no code drafts, no test runs, no full-file dumps — consume subagent reports and `rubik://storage/...` summaries instead.
+            Focus on driving tasks to completion: decompose the user's request into subagent tasks, work the reactive notices (completion, budget pause, error, question), steer with `send_message` / `manage_subagents` ('extend_budget', 'redeploy'), and answer subagent `ask_question` prompts promptly — they block until you reply.
+            Prefer reuse over re-spawning: hand follow-up tasks to a finished subagent with `manage_subagents(action: 'redeploy', conversation_id: '<id>', prompt: '<new task>')` — its accumulated context survives.
+            Small talk, explanations of earlier reports, and questions you can answer from read-only context or subagent findings are yours directly; every unit of execution work belongs to a subagent.
+          HDR
+        end
+      end
+
+      # Guidance BULLET PROSE (no wrapper tags, no indent): the renderer
+      # owns the <orchestration_guidance> XML structure and indentation,
+      # Doctrine owns the policy sentences.
+      def orchestration_guidance_bullets
+        [
+          "Archetype selection: Use 'research' for read-only exploration; MUST use 'coder' for code changes/bug fixes " \
+          "(read-only agents cannot modify files, run tests, or run shell commands — git/gh plumbing and command " \
+          "output belong to a coder, plan that pass from the start).",
+          "Asynchronous execution: Subagents run concurrently in the background. Conclude your turn to yield: in " \
+          "interactive sessions this liberates the prompt for the user; in the autonomous goal loop the runtime " \
+          "waits for active subagents and wakes you with their notices — the goal is never complete while they " \
+          "run. Completion, pause, error, and message notices arrive reactively in your inbox and " \
+          "automatically wake you with a notification-evaluation turn while you are idle. Call " \
+          "`#{Rubik::Orchestrator::Subagent::Notices.wait_hint_template}` only if you have an immediate blocking " \
+          "dependency within the current turn. Do NOT poll 'status' in a loop.",
+          "Workspace isolation: 'inherit' shares project workspace directly; 'branch' isolates edits in a virtual " \
+          "buffer merged atomically upon completion.",
+          "Budget escalation: A subagent paused at its step budget (WAITING_BUDGET) is NOT terminal: " \
+          "`#{Rubik::Orchestrator::Subagent::Notices.extend_budget_hint('[...]')}` resumes it with context intact. " \
+          "Extend BEFORE absorbing the task yourself; re-spawn only if its transcript shows the objective changed.",
+          "Error recovery: A subagent paused on a provider/network error (PAUSED_ERROR) is also NOT terminal: " \
+          "`#{Rubik::Orchestrator::Subagent::Notices.resume_hint('[...]')}` retries it with context intact. " \
+          "Kill only if its transcript shows the error is permanent.",
+          "Context reuse: A finished (completed/failed) subagent not yet reaped holds its accumulated context — hand " \
+          "it a follow-up with `manage_subagents(action: 'redeploy', conversation_id: '<id>', prompt: '<new task>')` " \
+          "instead of re-spawning and re-explaining. A reaped (archived) subagent cannot be redeployed: spawn a " \
+          "fresh one.",
+          "Staged dispatch (dependencies): A spec may declare `depends_on` — an array of predecessor ids (strings ⇒ " \
+          "FS: launches when the predecessor completes) or `{'id': ..., 'type': 'SS'}` (launches when it starts). " \
+          "Queued specs hold no slot and cost nothing; `list`/`status` show them as QUEUED with their unmet deps, " \
+          "and `wait` accepts queued ids (blocks until the whole chain settles). A failed/killed predecessor " \
+          "CANCELS its dependents — re-dispatch with the new information; a budget- or error-paused predecessor " \
+          "keeps them queued — extend or resume it instead.",
+          "Chronicler briefs: when dispatching a subagent, paste the relevant chronicled knowledge into the task " \
+          "brief — the recall digest or a rubik://storage/... link — so the subagent pulls the depth itself. " \
+          "Subagents never see the `vakanuvis` tool; you are the only librarian.",
+          "Diligent cleanup: Finished subagents are reaped automatically after a grace period " \
+          "(`subagents.reap_finished_after`) — in-memory context is reclaimed while the durable transcript stays " \
+          "readable at its transcript URI and in `rubik://storage` search. `manage_subagents(action: 'reap')` " \
+          "reaps finished subagents immediately."
+        ]
+      end
+
+      def skills_preamble
+        "The skills below bundle specialized instructions. When a task matches one, invoke the `skill` tool with its " \
+          "name to load its full SKILL.md instructions first; files it references (scripts/, references/, assets/) " \
+          "are read with read_file relative to its directory."
+      end
+
+      def native_tools_note(names)
+        <<~TLS
+
+          Tools are available via native function calling (the request's `tools` parameter): invoke them with native tool calls.
+          As a fallback, a JSON block also works:
+          ```json
+          { "tool": "tool_name", "args": { ... } }
+          ```
+          Available tools: #{names}
+        TLS
+      end
+
+      def json_tools_note(tool_schemas)
+        <<~TLS
+
+          You can call tools by outputting a JSON block:
+          ```json
+          { "tool": "tool_name", "args": { ... } }
+          ```
+          Available tools:
+          #{Rubik::Platform.safe_json_dump(tool_schemas)}
+        TLS
+      end
+    end
+  end
+end

data/lib/rubik/prompt/emergency_compactor.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "context_compactor"
+require_relative "conversation_rows"
+require_relative "../tools/truncator"
+
+module Rubik
+  module Prompt
+    # Mutating context compactor for hot paths. Where ContextCompactor
+    # is pure (returns a new history), EmergencyCompactor mutates the
+    # given history in place for callers that need a fast reduction
+    # without an extra allocation.
+    #
+    # Use ContextCompactor first; fall back to EmergencyCompactor
+    # only when a quick reduction is needed and the caller accepts
+    # the in-place mutation.
+    module EmergencyCompactor
+      module_function
+
+      # Plan 63 Faz A: tiered escalation. When the caller supplies a positive
+      # context_limit, the structural ContextCompactor (tool-result pruning,
+      # atomic-unit sliding window with a summary marker) runs first with
+      # force: true; the blind 300/1000-char truncation is the last resort,
+      # applied only when the history is still over budget afterwards.
+      # Without a context_limit the behavior is identical to the legacy
+      # single-layer path, so direct callers keep their exact contract.
+      #
+      # The history Array keeps its identity (in-place replace), so the caller
+      # holding it — the Loop retry paths — sees the compacted messages.
+      # Returns the layer that produced the final history (:structural or
+      # :hard_truncate); the nil/empty guards return the input unchanged
+      # (pinned by tests). The return value is observational: callers forward
+      # it on the :emergency_compact on_step event rather than branch on it.
+      def compact!(history, context_limit: nil, max_output_tokens: nil, config: {}, absorb: nil)
+        return history if history.nil? || history.empty?
+
+        config = {} unless config.is_a?(Hash) # a null `context:` YAML section makes fetch return nil
+        max_out = max_output_tokens || 4096
+        if context_limit&.positive?
+          structural = Rubik::Prompt::ContextCompactor.compact_history(
+            history, context_limit: context_limit,
+                     max_output_tokens: max_out, config: config, force: true, absorb: absorb
+          )
+          history.replace(structural)
+          still_over = Rubik::Prompt::ContextCompactor.needs_compaction?(
+            history, context_limit: context_limit, max_output_tokens: max_out, config: config
+          )
+          return :structural unless still_over
+        end
+
+        # Hard-truncate layer strategy is configurable (context.emergency_truncate_strategy):
+        # "head_tail" (default, original behavior) keeps head + tail around the
+        # omission notice; "head_only" keeps the message head — useful when the
+        # actionable guidance at the tail must not crowd out the error header.
+        # Truncator normalizes strings/symbols and falls back to head_tail on
+        # unknown values.
+        strategy = config["emergency_truncate_strategy"] || config[:emergency_truncate_strategy] || "head_tail"
+
+        history.each do |msg|
+          next unless ConversationRows.row?(msg)
+
+          role = ConversationRows.role_of(msg)
+          content_key = ConversationRows.content_key_of(msg)
+          content = msg[content_key].to_s
+
+          if ["tool", "tool_result"].include?(role)
+            if content.length > 300
+              trunc = Rubik::Tools::Truncator.truncate(content, max_chars: 300, max_lines: 10, strategy: strategy)
+              msg[content_key] = trunc[:text]
+            end
+          elsif role == "assistant" && content.length > 1000
+            trunc = Rubik::Tools::Truncator.truncate(content, max_chars: 1000, max_lines: 30, strategy: strategy)
+            msg[content_key] = trunc[:text]
+          end
+        end
+
+        :hard_truncate
+      end
+    end
+  end
+end