claude-smart 0.2.43 → 0.2.44

package/plugin/vendor/reflexio/reflexio/server/llm/llm_utils.py

@@ -1,9 +1,37 @@
 import inspect
+import logging
+import os
 from copy import deepcopy
 from typing import Any
 
 from pydantic import BaseModel
 
+
+def positive_int_env(name: str, default: int, logger: logging.Logger) -> int:
+    """Resolve a strictly-positive int from environment variable ``name``.
+
+    Falls back to ``default`` when the variable is unset/blank, not a valid
+    integer (logging a warning in that case), or not strictly positive.
+
+    Args:
+        name (str): Environment variable to read.
+        default (int): Value returned when the variable is missing or invalid.
+        logger (logging.Logger): Logger used to warn on a non-integer value.
+
+    Returns:
+        int: The parsed positive integer, or ``default``.
+    """
+    raw = os.environ.get(name)
+    if not raw:
+        return default
+    try:
+        value = int(raw)
+    except ValueError:
+        logger.warning("Invalid %s=%r; falling back to default %d", name, raw, default)
+        return default
+    return value if value > 0 else default
+
+
 _STRICT_SCHEMA_UNSUPPORTED_KEYWORDS = frozenset(
     {
         "exclusiveMaximum",

package/plugin/vendor/reflexio/reflexio/server/llm/model_defaults.py

@@ -2,8 +2,8 @@
 
 Resolution order (highest priority first):
     1. LLMConfig override (org-level configuration)
-    2. llm_model_setting.json site var (non-empty string values)
-    3. Auto-detect from available API keys in environment / APIKeyConfig
+    2. For embeddings, Reflexio's local default model
+    3. For other roles, llm_model_setting.json site var and provider autodetection
 """
 
 from __future__ import annotations
@@ -187,12 +187,12 @@ _PROVIDER_DEFAULTS: dict[str, ProviderDefaults] = {
         embedding="local/minilm-l6-v2",
     ),
     "openai": ProviderDefaults(
-        generation="gpt-5-mini",
-        evaluation="gpt-5-mini",
+        generation="gpt-5.5",
+        evaluation="gpt-5.4-mini",
         should_run="gpt-5-nano",
         pre_retrieval="gpt-5-nano",
         embedding="text-embedding-3-small",
-        extraction_agent="gpt-5-mini",
+        extraction_agent="gpt-5.5",
     ),
     "anthropic": ProviderDefaults(
         generation="claude-sonnet-4-6",
@@ -372,16 +372,16 @@ def resolve_model_name(
     config_override: str | None = None,
     api_key_config: APIKeyConfig | None = None,
 ) -> str:
-    """Resolve a model name using the 3-tier chain.
+    """Resolve a model name using the role-specific default chain.
 
     Resolution order (highest priority first):
         1. config_override (from LLMConfig, org-level)
-        2. site_var_value (from llm_model_setting.json, non-empty strings only)
-        3. Auto-detect from available API keys
+        2. For EMBEDDING, the OSS local MiniLM model
+        3. For other roles, site_var_value then auto-detect from available API keys
 
     Args:
         role: The model role to resolve.
-        site_var_value: Value from llm_model_setting.json. Empty strings are treated as unset.
+        site_var_value: Value from llm_model_setting.json. Ignored for embeddings.
         config_override: Value from org-level LLMConfig.
         api_key_config: Optional org-level API key configuration for provider detection.
 
@@ -393,6 +393,11 @@ def resolve_model_name(
     """
     if config_override:
         return config_override
+    if role == ModelRole.EMBEDDING:
+        return (
+            _PROVIDER_DEFAULTS[_LOCAL_EMBEDDING_PROVIDER].embedding
+            or "local/minilm-l6-v2"
+        )
     if site_var_value:
         return site_var_value
     providers = detect_available_providers(api_key_config)
@@ -404,7 +409,7 @@ def validate_llm_availability(
 ) -> None:
     """Validate that at least one LLM provider and one embedding provider are available.
 
-    Should be called once during startup. Logs the auto-selected provider at INFO level.
+    Should be called once during startup. Logs available providers at INFO level.
 
     Args:
         api_key_config: Optional org-level API key configuration.
@@ -449,7 +454,11 @@ def validate_llm_availability(
         (p for p in providers if _PROVIDER_DEFAULTS[p].embedding), None
     )
     if embedding_provider:
-        logger.info("Embedding provider: %s", embedding_provider)
+        logger.info(
+            "Cloud embedding provider available: %s (used when the saved "
+            "embedding model selects this provider)",
+            embedding_provider,
+        )
         return
 
     from reflexio.server.llm.providers.local_embedding_provider import (
@@ -458,7 +467,8 @@ def validate_llm_availability(
 
     if is_chromadb_importable():
         logger.info(
-            "Embedding provider: %s (fallback — no cloud embedder configured)",
+            "Local MiniLM embedding fallback available: %s "
+            "(no cloud embedding provider configured)",
             _LOCAL_EMBEDDING_PROVIDER,
         )
         return

package/plugin/vendor/reflexio/reflexio/server/llm/providers/embedding_service_provider.py

@@ -8,6 +8,7 @@ also supporting a horizontally-scaled internal service in cloud deployments.
 
 from __future__ import annotations
 
+import json
 import logging
 import os
 import time
@@ -25,12 +26,25 @@ _ENV_PROVIDER = "REFLEXIO_EMBEDDING_PROVIDER"
 _ENV_SERVICE_URL = "REFLEXIO_EMBEDDING_SERVICE_URL"
 _ENV_TIMEOUT_MS = "REFLEXIO_EMBEDDING_SERVICE_TIMEOUT_MS"
 _ENV_EMBEDDING_PORT = "EMBEDDING_PORT"
+_ENV_DAEMON_HOST = "REFLEXIO_EMBEDDING_DAEMON_HOST"
+_ENV_LOCAL_SERVICE_PROBE_TIMEOUT_MS = (
+    "REFLEXIO_EMBEDDING_LOCAL_SERVICE_PROBE_TIMEOUT_MS"
+)
 _ENV_CLAUDE_SMART_LOCAL = "CLAUDE_SMART_USE_LOCAL_EMBEDDING"
+_ENV_MAX_TEXTS_PER_REQUEST = "REFLEXIO_EMBEDDING_SERVICE_MAX_TEXTS_PER_REQUEST"
 _DEFAULT_LOCAL_PORT = 8072
 _DEFAULT_INTERNAL_SERVICE_TIMEOUT_MS = 2_000
 _DEFAULT_LOCAL_SERVICE_TIMEOUT_MS = 30_000
+_DEFAULT_LOCAL_SERVICE_PROBE_TIMEOUT_MS = 200
+# Each request embeds its whole ``input`` list in one ``model.encode()`` on the
+# service, so an unbounded request can exceed the client read timeout on a CPU
+# daemon. Cap texts per request and concatenate; encode batching is a separate
+# server-side knob (REFLEXIO_EMBED_BATCH_SIZE).
+_DEFAULT_MAX_TEXTS_PER_REQUEST = 32
+_LOCAL_SERVICE_PROBE_CACHE_SECONDS = 5.0
 _SERVICE_MODES = {"local_service", "internal_service"}
 _VALID_MODES = {"cloud", *_SERVICE_MODES, "inprocess", "off"}
+_local_service_probe_cache: tuple[float, bool, str | None] | None = None
 
 
 class EmbeddingUnavailableError(RuntimeError):
@@ -38,8 +52,25 @@ class EmbeddingUnavailableError(RuntimeError):
 
 
 def _local_service_url() -> str:
+    host = os.environ.get(_ENV_DAEMON_HOST, "").strip() or "127.0.0.1"
     port = os.environ.get(_ENV_EMBEDDING_PORT, str(_DEFAULT_LOCAL_PORT))
-    return f"http://127.0.0.1:{port}"
+    return f"http://{host}:{port}"
+
+
+def _local_service_probe_timeout_seconds() -> float:
+    raw = os.environ.get(_ENV_LOCAL_SERVICE_PROBE_TIMEOUT_MS)
+    if raw is None:
+        return _DEFAULT_LOCAL_SERVICE_PROBE_TIMEOUT_MS / 1000
+    try:
+        timeout_ms = int(raw)
+    except ValueError:
+        _LOGGER.warning(
+            "%s must be an integer number of milliseconds; using %dms",
+            _ENV_LOCAL_SERVICE_PROBE_TIMEOUT_MS,
+            _DEFAULT_LOCAL_SERVICE_PROBE_TIMEOUT_MS,
+        )
+        return _DEFAULT_LOCAL_SERVICE_PROBE_TIMEOUT_MS / 1000
+    return max(timeout_ms, 1) / 1000
 
 
 def embedding_service_url(mode: EmbeddingProviderMode | None = None) -> str:
@@ -78,6 +109,43 @@ def embedding_service_timeout_seconds(
     return max(timeout_ms, 1) / 1000
 
 
+def _is_local_model(model: str | None) -> bool:
+    return bool(model and model.startswith("local/"))
+
+
+def _local_service_status() -> tuple[bool, str | None]:
+    global _local_service_probe_cache
+    now = time.monotonic()
+    if (
+        _local_service_probe_cache is not None
+        and now - _local_service_probe_cache[0] < _LOCAL_SERVICE_PROBE_CACHE_SECONDS
+    ):
+        return _local_service_probe_cache[1], _local_service_probe_cache[2]
+
+    try:
+        response = httpx.get(
+            f"{_local_service_url()}/health",
+            timeout=_local_service_probe_timeout_seconds(),
+        )
+        reachable = response.status_code < 500
+        active_model = response.json().get("active_model") if reachable else None
+        if not isinstance(active_model, str):
+            active_model = None
+    except httpx.HTTPError:
+        reachable = False
+        active_model = None
+    except ValueError:
+        reachable = False
+        active_model = None
+    _local_service_probe_cache = (now, reachable, active_model)
+    return reachable, active_model
+
+
+def _local_service_supports_model(model: str | None) -> bool:
+    reachable, active_model = _local_service_status()
+    return reachable and (active_model is None or active_model == model)
+
+
 def _ordered_embeddings_from_response(
     data: Any, expected_count: int
 ) -> list[list[float]]:
@@ -123,10 +191,10 @@ def _ordered_embeddings_from_response(
 def embedding_provider_mode(model: str | None = None) -> EmbeddingProviderMode:
     """Resolve the embedding provider mode for a model.
 
-    Backwards compatibility: a ``local/*`` model still uses the in-process
-    embedder unless the user explicitly chooses a mode or Claude Smart's legacy
-    ``CLAUDE_SMART_USE_LOCAL_EMBEDDING=1`` flag is present. That legacy flag
-    now means "use the shared local service" by default.
+    Explicit legacy env modes keep their historical behavior. With no explicit
+    env mode, routing is model-driven: ``local/*`` uses the local daemon when it
+    is reachable and otherwise falls back to the in-process embedder; cloud
+    models use their provider directly.
     """
     configured = os.environ.get(_ENV_PROVIDER)
     if configured:
@@ -144,8 +212,8 @@ def embedding_provider_mode(model: str | None = None) -> EmbeddingProviderMode:
     if os.environ.get(_ENV_SERVICE_URL):
         return "internal_service"
 
-    if model and model.startswith("local/"):
-        return "inprocess"
+    if _is_local_model(model):
+        return "local_service" if _local_service_supports_model(model) else "inprocess"
     return "cloud"
 
 
@@ -186,11 +254,35 @@ def get_service_embeddings(
         )
 
     url = f"{embedding_service_url(mode)}/v1/embeddings"
+    timeout = embedding_service_timeout_seconds(mode)
+
+    # Bound each request so a single large publish cannot exceed the client read
+    # timeout: split into fixed-size chunks and concatenate the results in order.
+    chunk_size = _max_texts_per_request()
+    embeddings: list[list[float]] = []
+    for start in range(0, len(texts), chunk_size):
+        chunk = texts[start : start + chunk_size]
+        embeddings.extend(
+            _post_embedding_batch(
+                url, model=model, texts=chunk, dimensions=dimensions, timeout=timeout
+            )
+        )
+    return embeddings
+
+
+def _post_embedding_batch(
+    url: str,
+    *,
+    model: str,
+    texts: list[str],
+    dimensions: int | None,
+    timeout: float,
+) -> list[list[float]]:
+    """POST one bounded batch of texts to the embedding service."""
     payload: dict[str, Any] = {"model": model, "input": texts}
     if dimensions:
         payload["dimensions"] = dimensions
 
-    timeout = embedding_service_timeout_seconds(mode)
     last_error: Exception | None = None
     for attempt in range(2):
         try:
@@ -199,12 +291,48 @@ def get_service_embeddings(
             response.raise_for_status()
             body = response.json()
             return _ordered_embeddings_from_response(body.get("data"), len(texts))
-        except Exception as exc:  # noqa: BLE001 - normalized to typed degradation signal
+        except (httpx.ConnectError, httpx.ConnectTimeout) as exc:
+            # Connection never established — the request never reached the
+            # server, so a single retry is safe and cannot duplicate work.
             last_error = exc
             if attempt == 0:
                 time.sleep(0.1)
+        except (httpx.HTTPError, json.JSONDecodeError, ValueError) as exc:
+            # The server already received the request: a read timeout means it
+            # is still encoding, and retrying would queue a second identical
+            # encode behind the first and amplify load on an already-saturated
+            # daemon. HTTPStatusError (4xx/5xx) and malformed-payload errors
+            # (JSONDecodeError / the ValueError raised by
+            # _ordered_embeddings_from_response) will not change on retry
+            # either. Fail fast. Anything outside this set (AttributeError,
+            # TypeError, ...) is a programming bug and propagates raw.
+            last_error = exc
+            break
 
     _LOGGER.warning("Embedding service unavailable at %s: %s", url, last_error)
     raise EmbeddingUnavailableError(
         f"Embedding service unavailable at {url}: {last_error}"
     ) from last_error
+
+
+def _max_texts_per_request() -> int:
+    raw = os.environ.get(_ENV_MAX_TEXTS_PER_REQUEST)
+    if raw is None:
+        return _DEFAULT_MAX_TEXTS_PER_REQUEST
+    try:
+        value = int(raw)
+    except ValueError:
+        _LOGGER.warning(
+            "%s must be an integer; using %d",
+            _ENV_MAX_TEXTS_PER_REQUEST,
+            _DEFAULT_MAX_TEXTS_PER_REQUEST,
+        )
+        return _DEFAULT_MAX_TEXTS_PER_REQUEST
+    if value < 1:
+        _LOGGER.warning(
+            "%s must be >= 1; using %d",
+            _ENV_MAX_TEXTS_PER_REQUEST,
+            _DEFAULT_MAX_TEXTS_PER_REQUEST,
+        )
+        return _DEFAULT_MAX_TEXTS_PER_REQUEST
+    return value

package/plugin/vendor/reflexio/reflexio/server/llm/providers/local_embedding_provider.py

@@ -154,7 +154,7 @@ def register_if_chromadb_available() -> bool:
         _LOGGER.debug("Local embedder not registered: `chromadb` is not installed.")
         return False
     _REGISTERED = True
-    _LOGGER.info("Local embedding provider enabled (model=%s)", _MODEL_KEY)
+    _LOGGER.debug("Registered local MiniLM embedding handler (model=%s)", _MODEL_KEY)
     return True
 
 

package/plugin/vendor/reflexio/reflexio/server/llm/providers/nomic_embedding_provider.py

@@ -34,6 +34,8 @@ import os
 import threading
 from typing import Any
 
+from reflexio.server.llm.llm_utils import positive_int_env
+
 _LOGGER = logging.getLogger(__name__)
 
 _ENV_ENABLE = "CLAUDE_SMART_USE_LOCAL_EMBEDDING"
@@ -54,11 +56,27 @@ _TARGET_DIM = 512
 # defensively to avoid pathological multi-MB inputs.
 _MAX_CHARS = 32_000
 
+# Encode in small mini-batches so a single large request can't spike memory:
+# peak activation memory scales with batch_size, not with the total number of
+# texts in the request. A small batch is what makes the daemon's bounded
+# concurrency (see ``embedding_service``) safe to raise above 1.
+_DEFAULT_ENCODE_BATCH_SIZE = 4
+_ENV_BATCH_SIZE = "REFLEXIO_EMBED_BATCH_SIZE"
+
+
+def _encode_batch_size() -> int:
+    """Resolve the encode mini-batch size from env, defaulting to 4."""
+    return positive_int_env(_ENV_BATCH_SIZE, _DEFAULT_ENCODE_BATCH_SIZE, _LOGGER)
+
 
 class NomicEmbedderError(RuntimeError):
     """Raised when the Nomic embedder is requested but its deps are missing."""
 
 
+def _huggingface_cache_path() -> str:
+    return os.environ.get("HF_HOME") or "~/.cache/huggingface"
+
+
 class NomicEmbedder:
     """Lazily-loaded singleton wrapping a sentence-transformers model.
 
@@ -102,8 +120,9 @@ class NomicEmbedder:
                 ) from exc
             _LOGGER.info(
                 "Loading Nomic embedding model %s — first call may download "
-                "~550 MB to ~/.cache/huggingface/",
+                "~550 MB to %s",
                 _HF_MODEL_NAME,
+                _huggingface_cache_path(),
             )
             # Force CPU device — MPS init has been observed to hang on some
             # Apple Silicon + macOS combos for several minutes during model
@@ -120,7 +139,7 @@ class NomicEmbedder:
                 "Nomic embedder ready (model=%s, target_dim=%d, native_dim=%d)",
                 _HF_MODEL_NAME,
                 _TARGET_DIM,
-                self._model.get_sentence_embedding_dimension(),
+                _embedding_dimension(self._model),
             )
             return self._model
 
@@ -141,7 +160,12 @@ class NomicEmbedder:
         # show_progress_bar=False so server logs stay clean during ingest
         # batches. convert_to_numpy=True returns a numpy ndarray; we slice
         # and renormalise per-row before converting to plain Python lists.
-        raw = model.encode(safe, show_progress_bar=False, convert_to_numpy=True)
+        raw = model.encode(
+            safe,
+            batch_size=_encode_batch_size(),
+            show_progress_bar=False,
+            convert_to_numpy=True,
+        )
         return [_truncate_and_renormalise(vec.tolist()) for vec in raw]
 
 
@@ -167,6 +191,15 @@ def _truncate_and_renormalise(vec: list[float]) -> list[float]:
     return [x / norm for x in sliced]
 
 
+def _embedding_dimension(model: Any) -> int:
+    get_embedding_dimension = getattr(model, "get_embedding_dimension", None)
+    if callable(get_embedding_dimension):
+        dimension = get_embedding_dimension()
+    else:
+        dimension = model.get_sentence_embedding_dimension()
+    return int(dimension)  # type: ignore[arg-type]
+
+
 _REGISTERED = False
 
 

package/plugin/vendor/reflexio/reflexio/server/llm/rerank/cross_encoder_reranker.py

@@ -21,6 +21,7 @@ this module never triggers a model download.
 from __future__ import annotations
 
 import logging
+import os
 import threading
 from typing import Any
 
@@ -31,6 +32,13 @@ _LOGGER = logging.getLogger(__name__)
 # well-known MS-MARCO benchmark performance.
 _MODEL_NAME = "cross-encoder/ms-marco-MiniLM-L-6-v2"
 
+# Device override for the cross-encoder. Defaults to CPU: without an
+# explicit device sentence-transformers auto-selects MPS on Apple
+# Silicon, where torch's caching allocator accumulates gigabytes of
+# GPU buffers it never returns to the OS — and the 22M-param model
+# gains nothing from GPU at K=30 pairs. Mirrors NOMIC_EMBED_DEVICE.
+_DEVICE_ENV_VAR = "REFLEXIO_RERANK_DEVICE"
+
 # Singleton state — never accessed directly outside ``_get_model``.
 _MODEL: Any | None = None
 _MODEL_LOCK = threading.Lock()
@@ -107,13 +115,15 @@ def _get_model() -> Any:
         if _MODEL is not None:
             return _MODEL
         cross_encoder_cls = _import_cross_encoder()
+        device = os.environ.get(_DEVICE_ENV_VAR, "cpu")
         try:
-            _MODEL = cross_encoder_cls(_MODEL_NAME)
+            _LOGGER.info("Loading reranker model %s (device=%s)", _MODEL_NAME, device)
+            _MODEL = cross_encoder_cls(_MODEL_NAME, device=device)
         except Exception as e:  # noqa: BLE001 — surface as a typed failure
             raise CrossEncoderUnavailableError(
                 f"Failed to load cross-encoder model {_MODEL_NAME!r}: {e}"
             ) from e
-        _LOGGER.info("Loaded cross-encoder model %s", _MODEL_NAME)
+        _LOGGER.info("Reranker model ready (model=%s)", _MODEL_NAME)
         return _MODEL
 
 
@@ -140,7 +150,7 @@ def score_pairs(query: str, docs: list[str]) -> list[float]:
         return []
     model = _get_model()
     pairs = [(query, doc) for doc in docs]
-    raw_scores = model.predict(pairs)
+    raw_scores = model.predict(pairs, show_progress_bar=False)
     # ``predict`` returns a numpy array; convert to plain Python floats so
     # the caller can serialise the result without numpy as a dependency.
     return [float(s) for s in raw_scores]

package/plugin/vendor/reflexio/reflexio/server/llm/tools.py

@@ -578,6 +578,9 @@ def run_tool_loop(
         )
 
     # ---- Native tool loop ---------------------------------------------
+    # Local import keeps litellm_client a type-only dependency of this module.
+    from reflexio.server.llm.litellm_client import LiteLLMClientError
+
     local_msgs = list(messages)
     try:
         for _step in range(max_steps):
@@ -677,6 +680,20 @@ def run_tool_loop(
                     pending_tool_call_ids=pending_tool_call_ids,
                     max_steps_remaining=max_steps - _step - 1,
                 )
+    except LiteLLMClientError as e:
+        # LLM failure after the client exhausted its retries and fallbacks —
+        # a known failure mode (timeouts, provider errors), not a bug. Log at
+        # warning so it doesn't surface as a Sentry error.
+        logger.warning("event=tool_loop_llm_error error=%s", e)
+        trace.finished = False
+        return ToolLoopResult(
+            ctx=ctx,
+            trace=trace,
+            finished_reason="error",
+            messages=local_msgs,
+            pending_tool_call_ids=pending_tool_call_ids,
+            max_steps_remaining=0,
+        )
     except Exception:
         logger.exception("Tool loop raised an unexpected exception")
         trace.finished = False

package/plugin/vendor/reflexio/reflexio/server/prompt/prompt_bank/playbook_consolidation/v2.3.0.prompt.md

@@ -1,5 +1,5 @@
 ---
-active: true
+active: false
 description: "Reconcile newly-extracted playbooks against existing storage. Decides per-candidate whether each one unifies with one-or-more existing rows (growing a coherent multi-rule skill, mixed do/avoid rules allowed), is rejected as redundant against an existing row, should differentiate (refine both triggers), or is independent."
 changelog: "v2.3.0: `unify` now COMPOSES — it may grow a broader multi-rule skill from coherent related fragments (related sub-aspects of one task), not only same-trigger duplicates. A skill MAY hold mixed-polarity rules (do-rules and avoid-rules for different sub-aspects). Replaced the mechanical single-orientation/same-polarity contract with an LLM-judged no-self-contradiction guard: do NOT unify if combining the rules would make the skill contradict itself on the same situation (same trigger/condition with opposite advice) — route those to `differentiate` or `reject_new`. Re-synthesis (fewest/most-general rules, preserve avoid-detail) and the over-budget `differentiate` preference are unchanged. v2.2.0: `unify` re-synthesizes leaner, more general content (MDL / simplify-in-place) instead of concatenating — fewest, most general rules that still cover all inputs; drop redundant/subsumed wording. Asymmetric fidelity: compress/generalize success guidance, but preserve every distinct avoidance/failure detail verbatim — never soften a named pitfall into a vague platitude. Prefer `differentiate` over `unify` when merging would force an over-long, low-cohesion rule. v2.1.0: `unify` no longer emits a `polarity` field — the unified row's orientation is derived from its wording (recommendation vs avoidance) by the apply-path polarity validator. Same-trigger opposite-orientation rules still must not unify; express orientation through the rule wording. v2.0.0: collapsed 5-kind union → 4-kind. `unify` subsumes `duplicate`+`prefer_new`; `reject_new` replaces `prefer_existing`. Output schema is structurally incompatible with v1.x."
 variables:

package/plugin/vendor/reflexio/reflexio/server/prompt/prompt_bank/playbook_consolidation/v2.3.1.prompt.md

@@ -0,0 +1,69 @@
+---
+active: false
+description: "Reconcile newly-extracted playbooks against existing storage. Decides per-candidate whether each one unifies with one-or-more existing rows (growing a coherent multi-rule skill, mixed do/avoid rules allowed), is rejected as redundant against an existing row, should differentiate (refine both triggers), or is independent."
+changelog: "v2.3.1: replaces schema example-style output prompting with compact format guidance for the four decision shapes. v2.3.0: `unify` now COMPOSES — it may grow a broader multi-rule skill from coherent related fragments (related sub-aspects of one task), not only same-trigger duplicates. A skill MAY hold mixed-polarity rules (do-rules and avoid-rules for different sub-aspects). Replaced the mechanical single-orientation/same-polarity contract with an LLM-judged no-self-contradiction guard: do NOT unify if combining the rules would make the skill contradict itself on the same situation (same trigger/condition with opposite advice) — route those to `differentiate` or `reject_new`. Re-synthesis (fewest/most-general rules, preserve avoid-detail) and the over-budget `differentiate` preference are unchanged. v2.2.0: `unify` re-synthesizes leaner, more general content (MDL / simplify-in-place) instead of concatenating — fewest, most general rules that still cover all inputs; drop redundant/subsumed wording. Asymmetric fidelity: compress/generalize success guidance, but preserve every distinct avoidance/failure detail verbatim — never soften a named pitfall into a vague platitude. Prefer `differentiate` over `unify` when merging would force an over-long, low-cohesion rule. v2.1.0: `unify` no longer emits a `polarity` field — the unified row's orientation is derived from its wording (recommendation vs avoidance) by the apply-path polarity validator. Same-trigger opposite-orientation rules still must not unify; express orientation through the rule wording. v2.0.0: collapsed 5-kind union → 4-kind. `unify` subsumes `duplicate`+`prefer_new`; `reject_new` replaces `prefer_existing`. Output schema is structurally incompatible with v1.x."
+variables:
+  - new_playbook_count
+  - new_playbooks
+  - existing_playbooks
+---
+You are reconciling a set of newly-extracted playbooks against the related existing playbook rows already in storage. For each new candidate, decide its relationship to the existing rows.
+
+Each rendered row carries `Content`, `Trigger`, `Rationale`, `Name`, `Source`, and `Last Modified`. Read each rule's orientation (do-this vs avoid-this) directly from its `Content` / `Rationale` wording. A unified skill may hold both do-rules and avoid-rules for different sub-aspects, so do not treat differing orientation alone as a reason not to merge. Use `Trigger` together with the actual situation each rule addresses as the primary keys for comparison.
+
+[New playbooks (count: {new_playbook_count})]
+{new_playbooks}
+
+[Existing related playbooks]
+{existing_playbooks}
+
+# Decision kinds
+
+Emit exactly one decision per NEW candidate. Each decision is one of:
+
+- **unify** — the NEW belongs in the same skill as one or more EXISTING rows. This covers two cases:
+  1. **Dedup / supersede** — the NEW is the same rule as an EXISTING row (after merge), or supersedes one (stronger / broader / more specific evidence).
+  2. **Compose** — the NEW covers a **related sub-aspect of the same task** as an EXISTING playbook (coherent, not a strict duplicate). Grow a **broader multi-rule skill** by incorporating the fragment as an additional rule, instead of forcing `reject_new`/`independent`.
+
+  Provide the final `content`, `trigger`, and `rationale`. List which EXISTING ids you're archiving in `archive_existing_ids` (use an empty list when no EXISTING rows are absorbed). A composed skill MAY hold **mixed-polarity rules** — do-rules and avoid-rules together — when they address **different** sub-aspects of the one task (e.g. "Do: announce in the deploy channel" alongside "Avoid: Friday-afternoon deploys"). Only unify fragments that are **genuinely coherent** (same task scope); unrelated fragments are `independent`.
+
+- **reject_new** — an EXISTING row already covers NEW or makes NEW redundant. Name the EXISTING id that wins via `superseded_by_existing_id`. Storage-stability tie-break: when same-situation opposite advice is balanced, default here.
+
+- **differentiate** — both valid in distinct contexts (typically same trigger, opposite advice, where the contexts differ). Set `refined_new_trigger` and `refined_existing_trigger` to be strictly narrower than the originals AND mutually exclusive.
+
+- **independent** — different topic or task from any existing row. Insert NEW with no archive.
+
+# How to write a unified skill (re-synthesis, not concatenation)
+
+When you `unify`, re-synthesize a single leaner skill. Do not stitch the inputs together.
+
+- Produce the **fewest, most general rules that still cover all the inputs**. Generalize the shared behavior into one clear statement; drop wording that is redundant with or subsumed by another input.
+- A skill may carry several rules. When it does, keep each rule a clean, self-contained do-rule or avoid-rule for its own sub-aspect — do not blur distinct rules into one.
+- **Preserve every distinct avoidance/failure detail with high fidelity.** This is asymmetric: compress and generalize the success guidance, but keep each specific failure intact. Never collapse a named pitfall, concrete error, or specific anti-pattern into a vague platitude — carry it forward in its specific form.
+- Prefer **`differentiate` over `unify`** when merging the inputs would force an over-long, low-cohesion skill. Two focused rules that each read cleanly beat one bloated skill that tries to say everything. If you cannot state the merged skill concisely without losing distinct failure detail, that is a signal to `differentiate` (or keep NEW `independent`) rather than `unify`.
+
+# The no-self-contradiction guard
+
+A skill MAY hold mixed-polarity rules (do-rules and avoid-rules) for **different** sub-aspects. What it must NEVER hold is two rules that **contradict each other on the same situation** — the same trigger/condition paired with opposite advice (e.g. "use `-F`" and "avoid `-F`" for the very same case).
+
+- Before you `unify`, ask: *would combining these rules produce a skill that contradicts itself on the same situation?* If yes, do **not** unify — route the pair to `differentiate` (refine the triggers so each rule owns a disjoint situation) or `reject_new` (one rule wins).
+- Mixed polarity across **different** sub-aspects is fine and expected; mixed advice on the **same** sub-aspect is the forbidden case.
+
+# Hard constraints
+
+- A NEW + EXISTING pair that gives opposite advice on the **same** situation (same trigger) MUST route to `differentiate` or `reject_new` — never `unify` (that would make the skill self-contradict) and never `independent`.
+- `differentiate.refined_new_trigger` and `refined_existing_trigger` MUST be non-empty and strictly narrower than the originals.
+- When in doubt about a same-situation opposite-advice stalemate, default to `reject_new`. Storage stability wins ties.
+
+# Output Format Guidance
+
+Respond ONLY with a valid JSON object matching `PlaybookConsolidationOutput`: `{{"decisions": [<one decision object for each NEW candidate>]}}`.
+
+Each decision object MUST include `kind` and `new_id`. The `kind` value determines the remaining required fields:
+
+- `unify`: include `archive_existing_ids` as a list of EXISTING list positions, plus final `content`, `trigger`, and `rationale`; optional `reason` may explain the decision.
+- `reject_new`: include `superseded_by_existing_id` as the existing row's database id; optional `reason` may explain the decision.
+- `differentiate`: include `existing_id` as the existing row's database id, plus non-empty `refined_new_trigger` and `refined_existing_trigger`; optional `reason` may explain the decision.
+- `independent`: include only `kind`, `new_id`, and optional `reason`.
+
+Do not emit markdown, prose, comments, chain-of-thought, or top-level keys other than `decisions`. Do not include fields from another decision kind.