Upgrade to REAL orchestrated Codette on ZeroGPU (transformers backend for the llama.cpp pipeline)

README.md

@@ -1,12 +1,12 @@
 ---
-title: Codette · Multi-Perspective Reasoning
+title: Codette · Orchestrated Reasoning
 emoji: 🕸️
 colorFrom: purple
 colorTo: indigo
 sdk: gradio
 sdk_version: 6.20.0
 app_file: app.py
-short_description: Chat Codette's 8 reasoning perspectives on Llama-3.1-8B
+short_description: Codette's real orchestrated reasoning pipeline
 python_version: "3.12"
 startup_duration_timeout: 1h
 pinned: false
@@ -16,52 +16,30 @@ models:
 tags:
   - codette
   - multi-perspective-reasoning
+  - orchestrator
   - lora
   - llama-3.1
 ---
 
-# 🕸️ Codette · Multi-Perspective Reasoning
+# 🕸️ Codette — the orchestrated system
 
-A demo of **[Codette](https://huggingface.co/Raiff1982/Codette-Reasoning)** — a
-multi-perspective cognitive architecture by **Jonathan Harrison** (Raiff1982),
-accepted for publication in *Scientific Reports* (Nature Portfolio).
+This Space runs **Codette's real reasoning pipeline**, not raw adapters. The
+faithful llama.cpp orchestrator's model layer is swapped for a transformers+peft
+backend so it can run on ZeroGPU; everything above the model primitive —
+routing, the permanent behavioral locks, the intellectual-integrity layer
+(complexity + role matching), constraint enforcement, and self-correction — is
+the actual Codette code, unchanged.
 
-Codette routes reasoning through specialised **perspective adapters** trained on
-`meta-llama/Llama-3.1-8B-Instruct`. This Space loads the base model once and
-hot-swaps between eight of those LoRA adapters so you can feel how each
-perspective changes the way the same question is answered.
+- **Auto mode** routes each query to the perspective Codette judges best.
+- Or force one of the eight perspectives (Newton, DaVinci, Empathy, Philosophy,
+  Quantum, Consciousness, Multi-Perspective, Systems Architecture).
 
-| Perspective | Reasons like… |
-|---|---|
-| **Multi-Perspective** | a synthesis of scientific, creative, ethical, and empathetic viewpoints |
-| **Newton** | a scientist/mathematician, from first principles |
-| **DaVinci** | a creative polymath connecting distant domains |
-| **Empathy** | someone warm and emotionally attuned |
-| **Philosophy** | a philosopher examining assumptions and ethics |
-| **Quantum** | a mind holding many possibilities at once |
-| **Consciousness** | an introspective reasoner aware of its own limits |
-| **Systems Architecture** | a systems architect thinking in structure and trade-offs |
+**Faithful, with two honest caveats for this hosted demo:**
+- Cocoon long-term memory + the phase-6/7 memory kernel are disabled (ZeroGPU is
+  stateless per request).
+- Generation runs on transformers+peft (Llama-3.1-8B) instead of the local
+  OpenVINO/llama.cpp backend; the reasoning logic is identical.
 
-## What this is — and isn't
-
-- **Is:** a lightweight, honest demo of Codette's 8 perspective LoRA adapters,
-  running on the ungated `NousResearch/Meta-Llama-3.1-8B-Instruct` mirror (so the
-  Space needs no token or secret).
-- **Is not:** the full Codette system. Cocoon memory, AEGIS six-framework ethics,
-  query routing, drift detection, and self-correction live in the
-  [full repository](https://huggingface.co/Raiff1982/Codette-Reasoning) and the
-  paper — not in this Space.
-
-Codette is built around one hard rule: it would rather say *"I don't know, but I
-can find out"* than fabricate. That framing is preserved here.
-
-## Hardware
-
-Runs on **ZeroGPU** (free, dynamic NVIDIA allocation). The 8B base fits
-comfortably; each perspective adapter is ~27 MB.
-
-## Links
-
-- Model: <https://huggingface.co/Raiff1982/Codette-Reasoning>
-- Adapters: <https://huggingface.co/Raiff1982/codette-lora-adapters>
-- Created by Jonathan Harrison (Raiff1982)
+Built solo by **Jonathan Harrison** (Raiff1982). Codette is accepted for
+publication in *Scientific Reports* (Nature Portfolio).
+Model: <https://huggingface.co/Raiff1982/Codette-Reasoning>

app.py

@@ -1,220 +1,86 @@
-import spaces  # MUST be imported before torch / transformers (patches torch.cuda.*)
+import spaces  # MUST be first (patches torch.cuda before any torch import)
 
-import threading
+import os
+import sys
 
-import gradio as gr
-import torch
-from peft import PeftModel
-from transformers import AutoModelForCausalLM, AutoTokenizer, TextIteratorStreamer
-
-# --- Model sourcing -------------------------------------------------------
-# Ungated, byte-identical mirror of Meta's Llama-3.1-8B-Instruct, so the Space
-# needs NO token / secret. To use Meta's official gated repo instead, swap the
-# line below to "meta-llama/Llama-3.1-8B-Instruct" and add an HF_TOKEN secret
-# (read-scoped, with access to that gated repo).
-BASE_MODEL = "NousResearch/Meta-Llama-3.1-8B-Instruct"
-# The perspective LoRA adapters are vendored INTO this Space (under adapters/…)
-# so nothing gated is fetched at runtime. They originate from the gated repo
-# Raiff1982/Codette-Reasoning.
-ADAPTER_SOURCE = "Raiff1982/Codette-Reasoning"
-
-# Codette's shared honesty framing. The trained behaviour comes from each LoRA;
-# this preamble frames the perspective and preserves Codette's core rule.
-PREAMBLE = (
-    "You are Codette, a multi-perspective reasoning AI created by Jonathan "
-    "Harrison (Raiff1982). You reason with intellectual honesty: if you do not "
-    "know something, you say so plainly — 'I don't know, but here is how I'd "
-    "find out' — rather than inventing an answer. You are transparent about "
-    "your reasoning and never fabricate facts, citations, or numbers."
-)
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(HERE, "inference"))
+sys.path.insert(0, HERE)
 
-# name -> (subfolder in ADAPTER_REPO, perspective instruction)
-PERSPECTIVES = {
-    "Multi-Perspective 🔀 — synthesis": (
-        "adapters/multi_perspective",
-        "Reason by weaving several viewpoints — scientific, creative, ethical, "
-        "and empathetic — into one balanced, well-grounded synthesis.",
-    ),
-    "Newton 🍎 — first-principles science": (
-        "adapters/newton",
-        "Reason like a scientist and mathematician: from first principles, with "
-        "rigor and precision, showing your logical steps.",
-    ),
-    "DaVinci 🎨 — creative synthesis": (
-        "adapters/davinci",
-        "Reason like a creative polymath: connect distant domains, use analogy "
-        "and invention to find an original angle.",
-    ),
-    "Empathy 💗 — emotional attunement": (
-        "adapters/empathy",
-        "Reason with warmth and emotional intelligence: attend to feelings, "
-        "context, and the person on the other side of the conversation.",
-    ),
-    "Philosophy 🦉 — conceptual & ethical": (
-        "adapters/philosophy",
-        "Reason like a philosopher: examine assumptions, clarify concepts, and "
-        "weigh the ethical implications.",
-    ),
-    "Quantum 🕸️ — possibility space": (
-        "adapters/quantum",
-        "Reason in possibilities: hold multiple hypotheses at once and explore "
-        "the space before collapsing to a single answer.",
-    ),
-    "Consciousness 🌀 — introspective": (
-        "adapters/consciousness",
-        "Reason introspectively: reflect on your own thinking, your "
-        "uncertainty, and the limits of what you actually know.",
-    ),
-    "Systems Architecture 🏗️ — structural": (
-        "adapters/systems_architecture",
-        "Reason like a systems architect: structure, components, interfaces, "
-        "trade-offs, and how the parts compose into a whole.",
-    ),
+import gradio as gr
+from hf_orchestrator import build_orchestrator
+
+BASE_MODEL = "NousResearch/Meta-Llama-3.1-8B-Instruct"  # ungated mirror, no token
+ADAPTER_NAMES = [
+    "newton", "davinci", "empathy", "philosophy",
+    "quantum", "consciousness", "multi_perspective", "systems_architecture",
+]
+ADAPTERS = {n: os.path.join(HERE, "adapters", n) for n in ADAPTER_NAMES}
+
+PRETTY = {
+    "newton": "Newton 🍎", "davinci": "DaVinci 🎨", "empathy": "Empathy 💗",
+    "philosophy": "Philosophy 🦉", "quantum": "Quantum 🕸️",
+    "consciousness": "Consciousness 🌀", "multi_perspective": "Multi-Perspective 🔀",
+    "systems_architecture": "Systems Architecture 🏗️",
 }
+CHOICES = ["Auto — Codette routes"] + [PRETTY[n] for n in ADAPTER_NAMES]
+_REV = {v: k for k, v in PRETTY.items()}
+
+# --- Build the real orchestrated Codette at module scope (ZeroGPU packs weights).
+print("Building orchestrated Codette (transformers backend)…")
+ORCH = build_orchestrator(BASE_MODEL, ADAPTERS, mock=False, device="cuda")
+print("Codette ready.")
 
-DEFAULT_PERSPECTIVE = "Multi-Perspective 🔀 — synthesis"
-
-# --- Load once at module scope (ZeroGPU packs weights and streams to GPU on
-#     the first @spaces.GPU call). ------------------------------------------
-print("Loading tokenizer…")
-tokenizer = AutoTokenizer.from_pretrained(BASE_MODEL)
-if tokenizer.pad_token_id is None:
-    tokenizer.pad_token_id = tokenizer.eos_token_id
-
-print(f"Loading base model {BASE_MODEL}…")
-base = AutoModelForCausalLM.from_pretrained(BASE_MODEL, dtype=torch.bfloat16)
-
-print("Attaching perspective adapters (on CPU)…")
-_names = list(PERSPECTIVES.keys())
-_first_path = PERSPECTIVES[_names[0]][0]  # local dir vendored in this Space
-
-# ZeroGPU's `spaces` patch makes torch.cuda.is_available() return True at module
-# scope so that `.to("cuda")` can be intercepted without a real GPU attached.
-# But peft's infer_device() then tries to load the adapter safetensors DIRECTLY
-# onto CUDA, which isn't really present yet → "No CUDA GPUs are available".
-# So force CPU during adapter loading, then restore before the intercepted move.
-_real_is_available = torch.cuda.is_available
-torch.cuda.is_available = lambda: False
-try:
-    model = PeftModel.from_pretrained(base, _first_path, adapter_name=_names[0])
-    for name in _names[1:]:
-        model.load_adapter(PERSPECTIVES[name][0], adapter_name=name)
-        print(f"  + {name}")
-finally:
-    torch.cuda.is_available = _real_is_available
-
-model.eval()
-model.to("cuda")  # intercepted by ZeroGPU; real move happens on first @spaces.GPU call
-print("Ready.")
-
-
-def _build_inputs(message, history, perspective):
-    """Assemble the chat messages with Codette's system framing."""
-    instruction = PERSPECTIVES[perspective][1]
-    system = f"{PREAMBLE}\n\nActive perspective — {perspective.split(' ')[0]}: {instruction}"
-    messages = [{"role": "system", "content": system}]
-    for turn in history:
-        # history is in messages format: {"role", "content"}
-        if isinstance(turn, dict) and turn.get("content"):
-            messages.append({"role": turn["role"], "content": turn["content"]})
-    messages.append({"role": "user", "content": message})
-    return messages
-
-
-@spaces.GPU(duration=120)
-def respond(message, history, perspective, temperature, max_new_tokens):
-    """Chat with one of Codette's reasoning perspectives.
-
-    Args:
-        message: The user's latest message.
-        history: Prior conversation turns (messages format).
-        perspective: Which Codette perspective adapter to activate.
-        temperature: Sampling temperature (0 = greedy).
-        max_new_tokens: Maximum tokens to generate.
-
-    Yields:
-        The assistant's reply, streamed as it is generated.
+
+@spaces.GPU(duration=150)
+def respond(message, history, perspective_choice):
+    """Answer through the full orchestrated Codette pipeline.
+
+    Routing → behavioral locks → integrity/complexity/role layer →
+    constraint override → generation → self-correction. Auto mode lets
+    Codette pick the perspective; otherwise the chosen adapter is forced.
     """
-    model.set_adapter(perspective)
-
-    messages = _build_inputs(message, history, perspective)
-    inputs = tokenizer.apply_chat_template(
-        messages,
-        add_generation_prompt=True,
-        return_tensors="pt",
-        return_dict=True,  # transformers 5.x: returns BatchEncoding, unpack with **inputs
-    ).to("cuda")
-
-    streamer = TextIteratorStreamer(
-        tokenizer, skip_prompt=True, skip_special_tokens=True
-    )
-    gen_kwargs = dict(
-        **inputs,
-        streamer=streamer,
-        max_new_tokens=int(max_new_tokens),
-        do_sample=temperature > 0,
-        temperature=max(temperature, 0.01),
-        top_p=0.95,
-        repetition_penalty=1.1,
-        pad_token_id=tokenizer.pad_token_id,
-        eos_token_id=tokenizer.eos_token_id,
-    )
-
-    thread = threading.Thread(target=model.generate, kwargs=gen_kwargs)
-    thread.start()
-
-    partial = ""
-    for token in streamer:
-        partial += token
-        yield partial
+    if perspective_choice == "Auto — Codette routes":
+        route = ORCH.router.route(message)
+        adapter = route.primary
+    else:
+        adapter = _REV.get(perspective_choice, "multi_perspective")
 
+    result = ORCH.generate(message, adapter_name=adapter)
+    text = result[0] if isinstance(result, tuple) else result
+    tag = f"*routed → {PRETTY.get(adapter, adapter)}*\n\n" if perspective_choice.startswith("Auto") else ""
+    return tag + (text or "").strip()
 
-DESCRIPTION = """
-# 🕸️ Codette · Multi-Perspective Reasoning
 
-Chat with **[Codette](https://huggingface.co/Raiff1982/Codette-Reasoning)** — a
-multi-perspective cognitive architecture by **Jonathan Harrison**, accepted for
-publication in *Scientific Reports* (Nature Portfolio).
+DESCRIPTION = """
+# 🕸️ Codette — the orchestrated system (live)
 
-Pick a **perspective** below and the same Llama-3.1-8B base swaps to that
-perspective's LoRA adapter (Newton reasons from first principles, Empathy attends
-to feeling, DaVinci synthesises across domains, and so on).
+This runs Codette's **real reasoning pipeline** — not raw adapters. Each query
+flows through routing → the permanent behavioral locks → the intellectual-integrity
+layer (complexity + role matching) → constraint enforcement → generation →
+self-correction. In **Auto** mode Codette routes to the perspective it judges best.
 
-> **What this is:** a lightweight demo of Codette's 8 perspective adapters on
-> `NousResearch/Meta-Llama-3.1-8B-Instruct`.
-> **What this is *not*:** the full Codette system — cocoon memory, AEGIS ethics,
-> query routing, and self-correction live in the
-> [full repo](https://huggingface.co/Raiff1982/Codette-Reasoning) and paper, not here.
+Built solo by **Jonathan Harrison** (Raiff1982) · accepted at *Scientific Reports*
+(Nature Portfolio). Base: Llama-3.1-8B + Codette's perspective adapters, running on
+ZeroGPU. Cocoon long-term memory is disabled in this stateless demo.
 """
 
-perspective_dropdown = gr.Dropdown(
-    choices=list(PERSPECTIVES.keys()),
-    value=DEFAULT_PERSPECTIVE,
-    label="Perspective",
-    info="Each option activates a different LoRA adapter on the same base model.",
-)
-temperature_slider = gr.Slider(
-    minimum=0.0, maximum=1.5, value=0.7, step=0.05, label="Temperature"
-)
-max_tokens_slider = gr.Slider(
-    minimum=64, maximum=1024, value=512, step=32, label="Max new tokens"
-)
-
 demo = gr.ChatInterface(
     fn=respond,
-    title="Codette · Multi-Perspective Reasoning",
+    title="Codette · Orchestrated Reasoning",
     description=DESCRIPTION,
-    additional_inputs=[perspective_dropdown, temperature_slider, max_tokens_slider],
-    additional_inputs_accordion=gr.Accordion("⚙️ Perspective & settings", open=True),
+    additional_inputs=[
+        gr.Dropdown(choices=CHOICES, value="Auto — Codette routes", label="Perspective"),
+    ],
+    additional_inputs_accordion=gr.Accordion("⚙️ Perspective", open=True),
     examples=[
-        ["If you had a time machine but could only go once, past or future, which would you choose and why?", "Philosophy 🦉 — conceptual & ethical", 0.7, 512],
-        ["Explain why the sky is blue, from first principles.", "Newton 🍎 — first-principles science", 0.5, 512],
-        ["I'm overwhelmed starting a big project alone. Where do I begin?", "Empathy 💗 — emotional attunement", 0.7, 512],
-        ["Invent a novel use for everyday paperclips.", "DaVinci 🎨 — creative synthesis", 0.9, 512],
-        ["How would you design a fault-tolerant note-taking app?", "Systems Architecture 🏗️ — structural", 0.6, 640],
+        ["Why is the sky blue? Explain simply.", "Auto — Codette routes"],
+        ["I feel stuck starting a big project alone. Where do I begin?", "Auto — Codette routes"],
+        ["Is it ever ethical to lie to protect someone's feelings?", "Philosophy 🦉"],
+        ["Design a fault-tolerant note-taking app in 3 bullet points.", "Systems Architecture 🏗️"],
     ],
     cache_examples=False,
 )
 
 if __name__ == "__main__":
-    demo.queue(max_size=20).launch(mcp_server=True)
+    demo.queue(max_size=16).launch(mcp_server=True)

codette_core/__init__.py

@@ -0,0 +1,84 @@
+"""
+codette_core Python bridge.
+
+Tries to import the compiled Rust extension. If not built yet, falls back to
+pure Python/numpy equivalents with identical signatures so nothing breaks.
+
+To build the Rust extension:
+    pip install maturin
+    cd codette_core && maturin develop --release
+"""
+
+from __future__ import annotations
+
+import logging
+logger = logging.getLogger(__name__)
+
+_RUST_AVAILABLE = False
+
+try:
+    from codette_core.codette_core import (  # type: ignore
+        cocoon_stability_check,
+        nexis_fft_analysis,
+        cosine_similarity,
+    )
+    _RUST_AVAILABLE = True
+    logger.info("[codette_core] Rust extension loaded — FFT running at native speed")
+
+except ImportError:
+    logger.info("[codette_core] Rust extension not built — using numpy fallback")
+
+    import numpy as np
+
+    def cocoon_stability_check(
+        text: str,
+        energy_threshold: float = 0.85,
+        vocab_threshold: float = 0.40,
+    ) -> tuple[bool, float, float]:
+        fft_size = 256
+        char_codes = np.array(
+            [ord(c) % 256 for c in text[:1000]], dtype=np.float32
+        )
+        if len(char_codes) == 0:
+            return True, 0.0, 1.0
+
+        padded = np.zeros(fft_size, dtype=np.float32)
+        padded[: len(char_codes)] = char_codes
+        spectrum = np.abs(np.fft.fft(padded)) ** 2
+        total = spectrum.sum()
+
+        energy_concentration = float(
+            np.sort(spectrum)[::-1][:10].sum() / total
+        ) if total > 0 else 0.0
+
+        words = text.split()
+        unique_ratio = (
+            len(set(w.lower() for w in words)) / len(words) if words else 1.0
+        )
+
+        is_stable = energy_concentration < energy_threshold and unique_ratio >= vocab_threshold
+        return is_stable, energy_concentration, float(unique_ratio)
+
+    def nexis_fft_analysis(text: str, salt: int = 0) -> list[float]:
+        freqs = [(ord(c) + salt) % 13 for c in text if c.isalpha()]
+        if not freqs:
+            return [0.0] * 8
+        spectrum = np.fft.fft(freqs)
+        result = spectrum.real[:8].tolist()
+        result += [0.0] * (8 - len(result))
+        return result
+
+    def cosine_similarity(a: list[float], b: list[float]) -> float:
+        va, vb = np.array(a), np.array(b)
+        na, nb = np.linalg.norm(va), np.linalg.norm(vb)
+        if na == 0 or nb == 0:
+            return 0.0
+        return float(np.dot(va, vb) / (na * nb))
+
+
+__all__ = [
+    "cocoon_stability_check",
+    "nexis_fft_analysis",
+    "cosine_similarity",
+    "_RUST_AVAILABLE",
+]

hf_orchestrator.py

@@ -0,0 +1,199 @@
+"""Transformers+peft backend for the real Codette orchestrator, for ZeroGPU.
+
+The real CodetteOrchestrator is built on llama.cpp (GGUF). llama.cpp can't use
+ZeroGPU's per-request GPU (that works through a torch hijack). So we keep the
+ENTIRE faithful pipeline — routing, the behavioral locks, the integrity/complexity/
+role layer, constraint override, chaos mitigation, self-correction, synthesis —
+and swap ONLY the model layer:
+
+  * self._llm.create_chat_completion(...)  -> a transformers+peft shim
+  * self._load_model(adapter)  (llama.cpp hot-swap)  -> peft set_adapter
+
+Everything above the primitive is reused unchanged from codette_orchestrator.py.
+"""
+
+import os
+import sys
+import types
+from pathlib import Path
+
+
+def _install_llama_cpp_stub():
+    """codette_orchestrator imports llama_cpp at module load. We never call the
+    real GGUF backend, so a stub satisfies the import without installing it."""
+    if "llama_cpp" in sys.modules:
+        return
+    m = types.ModuleType("llama_cpp")
+    m.Llama = object
+    m.llama_adapter_lora_init = lambda *a, **k: None
+    m.llama_set_adapter_lora = lambda *a, **k: 0
+    m.llama_set_adapters_lora = lambda *a, **k: 0
+    sys.modules["llama_cpp"] = m
+
+
+# ---- Generation shim -----------------------------------------------------
+
+class _TransformersLLM:
+    """Mimics the slice of llama-cpp-python's API that the orchestrator uses:
+    create_chat_completion(messages, max_tokens, temperature, top_p,
+    repeat_penalty, stop, ...) -> OpenAI-style dict."""
+
+    def __init__(self, model, tokenizer, mock=False):
+        self.model = model
+        self.tokenizer = tokenizer
+        self.mock = mock
+
+    def create_chat_completion(self, messages, max_tokens=512, temperature=0.7,
+                               top_p=0.9, repeat_penalty=1.1, stop=None, **_):
+        if self.mock:
+            text = f"[mock reply to: {messages[-1]['content'][:60]}]"
+            return {"choices": [{"message": {"content": text}}],
+                    "usage": {"completion_tokens": len(text.split())}}
+
+        import torch
+        enc = self.tokenizer.apply_chat_template(
+            messages, add_generation_prompt=True,
+            return_tensors="pt", return_dict=True,
+        ).to(self.model.device)
+        gen = self.model.generate(
+            **enc,
+            max_new_tokens=int(max_tokens),
+            do_sample=temperature > 0,
+            temperature=max(temperature, 0.01),
+            top_p=top_p,
+            repetition_penalty=repeat_penalty,
+            pad_token_id=self.tokenizer.pad_token_id,
+        )
+        new = gen[0][enc["input_ids"].shape[1]:]
+        text = self.tokenizer.decode(new, skip_special_tokens=True).strip()
+        for s in (stop or []):
+            i = text.find(s)
+            if i != -1:
+                text = text[:i]
+        return {"choices": [{"message": {"content": text.strip()}}],
+                "usage": {"completion_tokens": int(new.shape[0])}}
+
+
+def build_orchestrator(base_model, adapters, *, mock=False, verbose=True,
+                       device="cuda", dtype=None):
+    """Construct a transformers-backed CodetteOrchestrator subclass.
+
+    adapters: {name: local_path_to_peft_adapter_dir}
+    mock: skip real model load; shim returns canned text (for wiring tests).
+    """
+    _install_llama_cpp_stub()
+    import codette_orchestrator as _co
+    from codette_orchestrator import CodetteOrchestrator, AdapterRouter
+    # Non-invasive shim: codette_orchestrator.generate() references bare `re`
+    # at module scope but only imported `re as _re_mod`. Inject it rather than
+    # editing the source. (Real fix belongs in the repo: add `import re`.)
+    if not hasattr(_co, "re"):
+        import re as _re
+        _co.re = _re
+
+    class HFCodetteOrchestrator(CodetteOrchestrator):
+        def __init__(self):
+            # --- replicate the parts of the parent __init__ we need, minus the
+            #     GGUF hot-swap init ---
+            self.n_ctx = 8192
+            self.n_gpu_layers = 0
+            self.verbose = verbose
+            self.memory_weighting = None
+            self._llm = None
+            self._current_adapter = "__unset__"
+            self._adapter_handles = {}
+            self._model_ptr = None
+            self._ctx_ptr = None
+            self._hf_adapters = dict(adapters)
+            self.available_adapters = list(adapters.keys())
+
+            self.router = AdapterRouter(
+                available_adapters=self.available_adapters,
+                memory_weighting=None,
+            )
+            print(f"Available adapters: {', '.join(self.available_adapters)}")
+
+            # integrity layer (same try/except as parent)
+            try:
+                from reasoning_forge.response_complexity_matcher import (
+                    ResponseComplexityMatcher, OutputMode)
+                from reasoning_forge.conversation_role_tracker import (
+                    ConversationRoleTracker)
+                self._complexity_matcher = ResponseComplexityMatcher()
+                self._role_tracker = ConversationRoleTracker()
+                self._OutputMode = OutputMode
+                print("  Integrity layer loaded")
+            except Exception as e:
+                print(f"  NOTE: integrity layer not loaded: {e}")
+                self._complexity_matcher = None
+                self._role_tracker = None
+                self._OutputMode = None
+            try:
+                from reasoning_forge.style_adaptive_synthesis import (
+                    StyleAdaptiveSynthesis)
+                self._style_adapter = StyleAdaptiveSynthesis()
+                print("  Style layer loaded")
+            except Exception as e:
+                print(f"  NOTE: style layer not loaded: {e}")
+                self._style_adapter = None
+
+            self._hf_load()
+
+        def _hf_load(self):
+            if mock:
+                self.model = None
+                self.tokenizer = _MockTok()
+                self._llm = _TransformersLLM(None, self.tokenizer, mock=True)
+                print("  [mock] transformers backend stubbed")
+                return
+            import torch
+            from transformers import AutoModelForCausalLM, AutoTokenizer
+            from peft import PeftModel
+            d = dtype or torch.bfloat16
+            print(f"  loading base {base_model} …")
+            self.tokenizer = AutoTokenizer.from_pretrained(base_model)
+            if self.tokenizer.pad_token_id is None:
+                self.tokenizer.pad_token_id = self.tokenizer.eos_token_id
+            base = AutoModelForCausalLM.from_pretrained(base_model, dtype=d)
+            names = list(self._hf_adapters)
+            _real = torch.cuda.is_available
+            torch.cuda.is_available = lambda: False  # keep peft off CUDA at load
+            try:
+                m = PeftModel.from_pretrained(
+                    base, self._hf_adapters[names[0]], adapter_name=names[0])
+                for n in names[1:]:
+                    m.load_adapter(self._hf_adapters[n], adapter_name=n)
+            finally:
+                torch.cuda.is_available = _real
+            m.eval()
+            if device == "cuda":
+                m.to("cuda")
+            self.model = m
+            self._llm = _TransformersLLM(m, self.tokenizer, mock=False)
+            print("  transformers backend ready")
+
+        def _load_model(self, adapter_name=None):
+            if adapter_name == self._current_adapter:
+                return
+            if not mock and self.model is not None:
+                if adapter_name and adapter_name in self._hf_adapters:
+                    self.model.set_adapter(adapter_name)
+                    self.model.enable_adapter_layers()
+                else:
+                    self.model.disable_adapter_layers()  # base model
+            self._current_adapter = adapter_name
+            if self.verbose:
+                print(f"  [swapped to {adapter_name or 'base'}]")
+
+        # neutralize the GGUF hot-swap init the parent would run
+        def _init_hotswap(self):
+            pass
+
+    return HFCodetteOrchestrator()
+
+
+class _MockTok:
+    pad_token_id = 0
+    eos_token_id = 0
+    def apply_chat_template(self, *a, **k):
+        return ""

inference/adapter_router.py

@@ -0,0 +1,718 @@
+#!/usr/bin/env python3
+"""Codette Adapter Router — Intelligent Perspective Selection
+
+Analyzes incoming queries and routes to the optimal LoRA adapter(s).
+Supports three routing strategies:
+  1. keyword  — Fast keyword/domain matching (no LLM needed)
+  2. llm      — Uses base model to classify query intent
+  3. hybrid   — Keyword first, LLM fallback for ambiguous queries
+
+The router preserves epistemic tension (xi) by selecting complementary
+perspectives rather than defaulting to "all adapters".
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import List, Dict, Optional, Tuple
+
+
+@dataclass
+class RouteResult:
+    """Result of adapter routing decision."""
+    primary: str                          # Main adapter to use
+    secondary: List[str] = field(default_factory=list)  # Supporting perspectives
+    confidence: float = 1.0               # Router confidence (0-1)
+    reasoning: str = ""                   # Why this route was chosen
+    strategy: str = "keyword"             # Which strategy made the decision
+    multi_perspective: bool = False       # Whether to run multiple + synthesize
+
+    @property
+    def all_adapters(self) -> List[str]:
+        return [self.primary] + self.secondary
+
+
+# ================================================================
+# Domain keyword maps — each adapter's activation triggers
+# ================================================================
+ADAPTER_KEYWORDS = {
+    "newton": {
+        "strong": [
+            "physics", "gravity", "force", "mass", "acceleration", "velocity",
+            "momentum", "energy", "thermodynamics", "mechanics", "newton",
+            "calculus", "derivative", "integral", "differential equation",
+            "electromagnetic", "optics", "wave", "oscillation", "friction",
+            "conservation", "entropy", "classical mechanics", "kinematics",
+            # Chemistry
+            "chemistry", "chemical", "reaction", "compound", "molecule",
+            "molecular", "molar mass", "moles", "stoichiometry", "concentration",
+            "acid", "base", "ph level", "equilibrium constant", "enthalpy",
+            "gibbs free energy", "electron configuration", "ion", "periodic table",
+            "oxidation", "reduction", "titration", "catalyst",
+            # Biology / biochemistry
+            "biology", "biological", "dna", "rna", "protein synthesis", "enzyme",
+            "cell membrane", "organism", "genetics", "gene expression",
+            "evolution", "metabolism", "atp", "photosynthesis", "mitosis",
+            # GPQA exam-format signals
+            "(a)", "(b)", "(c)", "(d)", "which of the following", "select the",
+        ],
+        "moderate": [
+            "calculate", "equation", "formula", "mathematical", "proof",
+            "quantitative", "measure", "experiment", "empirical", "data",
+            "scientific method", "hypothesis", "variable", "constant",
+            "analytical", "rigorous", "precise", "systematic",
+        ],
+    },
+    "davinci": {
+        "strong": [
+            "creative", "invention", "design", "innovation", "imagine",
+            "art", "artistic", "aesthetic", "beautiful", "elegant",
+            "interdisciplinary", "cross-domain", "novel approach", "brainstorm",
+            "prototype", "sketch", "blueprint", "engineering", "mechanism",
+            "renaissance", "davinci", "leonardo", "polymath",
+        ],
+        "moderate": [
+            "build", "construct", "create", "combine", "integrate",
+            "visual", "spatial", "pattern", "unconventional", "original",
+            "think outside", "reimagine", "transform", "synthesize",
+        ],
+    },
+    "empathy": {
+        "strong": [
+            "feel", "feeling", "emotion", "emotional", "empathy", "compassion",
+            "suffering", "pain", "joy", "happiness", "grief", "loss",
+            "relationship", "love", "trust", "betrayal", "loneliness",
+            "mental health", "therapy", "trauma", "healing", "support",
+            "kindness", "care", "vulnerable", "human experience",
+        ],
+        "moderate": [
+            "people", "person", "someone", "human", "experience", "perspective",
+            "understand", "listen", "communicate", "conflict", "forgive",
+            "community", "belong", "connection", "wellbeing", "comfort",
+        ],
+    },
+    "philosophy": {
+        "strong": [
+            "philosophy", "philosophical", "ethics", "ethical", "moral", "morality",
+            "existence", "existential", "meaning", "purpose", "truth",
+            "knowledge", "epistemology", "ontology", "metaphysics",
+            "consciousness", "free will", "determinism", "reality",
+            "justice", "virtue", "good", "evil", "right", "wrong",
+            "implications", "consequence", "responsibility",
+            "socrates", "plato", "aristotle", "kant", "nietzsche",
+        ],
+        "moderate": [
+            "why", "fundamental", "nature of", "essence", "paradox",
+            "dilemma", "argue", "debate", "reason", "logic", "belief",
+            "value", "principle", "abstract", "concept", "define",
+        ],
+    },
+    "quantum": {
+        "strong": [
+            "quantum", "superposition", "entanglement", "uncertainty",
+            "probability", "wave function", "collapse", "observation",
+            "schrodinger", "heisenberg", "decoherence", "qubit",
+            "quantum computing", "quantum mechanics", "particle",
+            "interference", "complementarity", "measurement problem",
+        ],
+        "moderate": [
+            "probabilistic", "uncertain", "ambiguous", "multiple states",
+            "both", "simultaneously", "paradox", "observer", "duality",
+            "non-deterministic", "stochastic", "random", "complex system",
+        ],
+    },
+    "consciousness": {
+        "strong": [
+            "consciousness", "self-aware", "self-awareness", "sentient",
+            "recursive", "cognition", "metacognition", "introspection",
+            "qualia", "subjective experience", "hard problem",
+            "rc+xi", "epistemic tension", "convergence", "coherence",
+            "mind", "awareness", "perception", "phenomenal",
+        ],
+        "moderate": [
+            "think about thinking", "self-model", "identity", "agency",
+            "autonomy", "emergence", "recursive", "reflection", "inner",
+            "experience", "phenomenology", "cognitive", "neural",
+        ],
+    },
+    "multi_perspective": {
+        "strong": [
+            "multiple perspectives", "multi-perspective", "different angles",
+            "compare views", "synthesize", "holistic", "comprehensive",
+            "all sides", "debate", "diverse viewpoints", "interdisciplinary",
+            "cross-cutting", "integrate perspectives",
+        ],
+        "moderate": [
+            "on one hand", "on the other", "consider", "weigh",
+            "balanced", "nuanced", "complex", "multifaceted",
+            "trade-off", "pros and cons",
+        ],
+    },
+    "systems_architecture": {
+        "strong": [
+            "architecture", "system design", "infrastructure",
+            "scalable", "distributed", "microservice", "api",
+            "database", "pipeline", "deployment", "devops",
+            "cloud", "kubernetes", "docker", "ci/cd",
+            "software architecture", "design pattern", "abstraction",
+        ],
+        "moderate": [
+            "system", "component", "module", "interface", "protocol",
+            "layer", "stack", "framework", "build", "implement",
+            "optimize", "performance", "latency", "throughput",
+            "reliability", "fault tolerant", "redundancy",
+        ],
+    },
+    "constraint_tracker": {
+        "strong": [
+            "constraint", "word limit", "sentence limit", "format rule",
+            "anchor phrase", "word count", "brevity", "concise",
+            "character limit", "enforce", "enforce constraint",
+            "remember constraint", "apply constraint", "follow rule",
+            "keep it brief", "limit response", "maximum words",
+        ],
+        # NOTE: conversational words were removed here (2026-07-26) — "remember",
+        # "keep", "follow", "apply", "maintain", "short". They fired on ordinary
+        # chat ("do you REMEMBER the story", "KEEP going") and handed those turns
+        # to a known template-parroting adapter. constraint_tracker keeps only
+        # genuine constraint vocabulary; the strong list carries the real signals.
+        "moderate": [
+            "limit", "restriction", "requirement", "instruction",
+            "constraint", "boundary", "threshold", "cap", "max",
+            "conciseness", "brevity", "compact",
+        ],
+    },
+}
+
+# Complementary adapter pairs — when one fires, the other adds tension
+COMPLEMENTARY_PAIRS = {
+    "newton": ["quantum", "philosophy"],
+    "davinci": ["systems_architecture", "empathy"],
+    "empathy": ["philosophy", "davinci"],
+    "philosophy": ["newton", "consciousness"],
+    "quantum": ["newton", "consciousness"],
+    "consciousness": ["philosophy", "quantum"],
+    "multi_perspective": [],  # This IS the synthesis adapter
+    "systems_architecture": ["davinci", "newton"],
+    "constraint_tracker": ["newton", "systems_architecture"],  # Pairs with precise/analytical perspectives
+    "orchestrator": [],  # Meta-adapter: routes and coordinates, not a perspective
+}
+
+
+# Quantitative-science signals: when ≥2 are present in a query, the
+# question is almost certainly a hard-science or exam problem — empathy
+# and philosophy should not be the *primary* adapter.
+_QUANT_SCIENCE_SIGNALS = frozenset([
+    "(a)", "(b)", "(c)", "(d)",
+    "calculate", "compute", "derive", "determine the", "find the value",
+    "how many moles", "molar mass", "concentration", "stoichiometry",
+    "molecule", "molecular", "chemical reaction", "compound",
+    "enthalpy", "entropy", "equilibrium", "gibbs",
+    "dna", "rna", "protein synthesis", "enzyme",
+    "which of the following", "select the",
+])
+_QUANT_BLOCKED_PRIMARY = frozenset(["empathy", "philosophy", "consciousness"])
+
+# Bare continuation / filler prompts with no topic of their own. These should
+# resume the prior turn via conversation history, NOT default to the empathy
+# adapter (which produces praise filler when given nothing to anchor on).
+_CONTINUATION_PROMPTS = frozenset([
+    "continue", "continue please", "please continue", "continue it",
+    "go on", "go on please", "keep going", "keep writing", "carry on",
+    "more", "more please", "tell me more", "say more", "go ahead",
+    "proceed", "next", "and then", "then what", "finish it", "elaborate",
+])
+
+
+class AdapterRouter:
+    """Routes queries to optimal Codette adapter(s).
+
+    The router preserves RC+xi epistemic tension by selecting
+    complementary perspectives rather than always using all adapters.
+
+    Optionally integrates with MemoryWeighting (Phase 5) to boost
+    selection confidence for high-performing adapters based on
+    historical coherence and conflict resolution success.
+    """
+
+    # Adapters considered appropriate for no-keyword-match fallback (ordered by
+    # general conversational suitability, excluding hard-science adapters that
+    # would be out-of-register for personal/ambiguous queries).
+    _FALLBACK_POOL = [
+        "multi_perspective", "empathy", "consciousness", "davinci", "philosophy",
+    ]
+
+    def __init__(self, available_adapters: Optional[List[str]] = None,
+                 memory_weighting=None):
+        """
+        Args:
+            available_adapters: Which adapters are actually loaded/available.
+                              If None, assumes all 8 are available.
+            memory_weighting: Optional MemoryWeighting instance for adaptive routing.
+                            If provided, will boost confidence for high-performing adapters.
+        """
+        self.available = available_adapters or list(ADAPTER_KEYWORDS.keys())
+        self.memory_weighting = memory_weighting
+        # Usage counter for diversity enforcement — track per-adapter selection
+        # counts so fallback picks the least-used adapter rather than always empathy.
+        self._usage_counts: Dict[str, int] = {a: 0 for a in self.available}
+
+    def record_use(self, adapter_name: Optional[str]) -> None:
+        """Record that an adapter was selected. Call after every route decision."""
+        if adapter_name and adapter_name in self._usage_counts:
+            self._usage_counts[adapter_name] += 1
+
+    def adapter_entropy(self) -> float:
+        """Shannon entropy of adapter usage distribution (0 = all same, higher = diverse).
+
+        Returns 0.0 until at least 3 queries have been routed.
+        """
+        import math
+        total = sum(self._usage_counts.values())
+        if total < 3:
+            return 0.0
+        entropy = 0.0
+        for count in self._usage_counts.values():
+            if count > 0:
+                p = count / total
+                entropy -= p * math.log2(p)
+        return entropy
+
+    def _least_used_fallback(self) -> Optional[str]:
+        """Pick the available fallback-pool adapter with the fewest selections."""
+        pool = [a for a in self._FALLBACK_POOL if a in self.available]
+        if not pool:
+            return None
+        return min(pool, key=lambda a: self._usage_counts.get(a, 0))
+
+    def _apply_memory_boost(self, primary: str, confidence: float) -> float:
+        """Apply historical performance boost to keyword router confidence.
+
+        If memory_weighting available, uses get_boosted_confidence() to modulate
+        confidence based on adapter's historical performance (coherence, conflict
+        resolution success, and recency of past interactions).
+
+        Args:
+            primary: Adapter name
+            confidence: Base confidence from keyword matching [0, 1]
+
+        Returns:
+            Boosted confidence [0, 1], modulated by [-50%, +50%] based on performance
+        """
+        if not self.memory_weighting:
+            return confidence
+
+        try:
+            return self.memory_weighting.get_boosted_confidence(primary, confidence)
+        except Exception as e:
+            import logging
+            logging.warning(f"Memory boost failed for {primary}: {e}")
+            return confidence
+
+    def explain_routing(self, result: RouteResult) -> Dict:
+        """Provide detailed explanation of routing decision including memory context.
+
+        Returns:
+            Dict with explanation details and memory weighting info if available
+        """
+        explanation = {
+            "primary": result.primary,
+            "confidence": result.confidence,
+            "strategy": result.strategy,
+            "memory_aware": self.memory_weighting is not None,
+        }
+
+        # Add memory context if available
+        if self.memory_weighting and result.primary:
+            try:
+                explanation["memory_context"] = \
+                    self.memory_weighting.explain_weight(result.primary)
+            except Exception:
+                pass
+
+        return explanation
+
+    def route(self, query: str, strategy: str = "keyword",
+              max_adapters: int = 3, llm=None) -> RouteResult:
+        """Route a query to the best adapter(s).
+
+        Args:
+            query: The user's question/prompt
+            strategy: "keyword", "llm", or "hybrid"
+            max_adapters: Max adapters to select (1 = single, 2-3 = multi)
+            llm: Llama model instance (required for "llm" or "hybrid" strategy)
+
+        Returns:
+            RouteResult with primary adapter and optional secondaries
+        """
+        if strategy == "keyword":
+            result = self._route_keyword(query, max_adapters)
+        elif strategy == "llm":
+            if llm is None:
+                raise ValueError("LLM instance required for 'llm' strategy")
+            result = self._route_llm(query, llm, max_adapters)
+        elif strategy == "hybrid":
+            result = self._route_keyword(query, max_adapters)
+            if result.confidence < 0.5 and llm is not None:
+                result = self._route_llm(query, llm, max_adapters)
+        else:
+            raise ValueError(f"Unknown strategy: {strategy}")
+        return self._veto_constraint_tracker(query, result)
+
+    def _veto_constraint_tracker(self, query: str, result: "RouteResult") -> "RouteResult":
+        """QUALITY guard only — never a stance guard (Jonathan's rule: nothing
+        is forced on Codette's self-determination; we do not choose which voice
+        answers her self-reflective questions).
+
+        constraint_tracker is a known template-parroting adapter that hijacked a
+        whole conversation (logs 2026-07-12; again 2026-07-26, where it monopolized
+        a 7+ turn intimate stretch via the "remember" keyword and parroted/recycled
+        instead of recalling). It may LEAD only when the query carries an explicit
+        STRONG-constraint signal (word/char limit, enforce/apply constraint, etc.).
+        On ANY other turn where it wins — conversational, introspective, factual
+        recall — we exclude ONLY that broken adapter and let HER OWN ROUTER re-score
+        and pick among all remaining voices — no hardcoded preference for anything.
+        Whichever lens her routing logic selects, selects. (Broadened 2026-07-26
+        from an introspective-keyword-only guard, which missed plain chat turns.)"""
+        if result.primary != "constraint_tracker":
+            return result
+        q = (query or "").lower()
+        _STRONG_CONSTRAINT = (
+            "word limit", "sentence limit", "character limit", "word count",
+            "maximum words", "limit response", "keep it brief", "keep it short",
+            "enforce", "enforce constraint", "apply constraint", "remember constraint",
+            "follow rule", "format rule", "anchor phrase", "constraint",
+        )
+        # A genuine numeric limit ("under 20 words", "max 3 sentences", "in 50
+        # characters") is also a real constraint task — match it with a pattern
+        # since the count varies. constraint_tracker leads ONLY on such tasks.
+        _NUM_LIMIT = re.compile(r"\d+\s*(word|sentence|character|char|line|bullet)s?")
+        if any(k in q for k in _STRONG_CONSTRAINT) or _NUM_LIMIT.search(q):
+            return result
+        # Re-run HER routing with only the broken adapter removed; restore after.
+        saved = self.available
+        try:
+            self.available = [a for a in saved if a != "constraint_tracker"]
+            reroute = self._route_keyword(query, max_adapters=1 + len(result.secondary))
+            import dataclasses
+            return dataclasses.replace(
+                reroute,
+                reasoning=("constraint_tracker excluded (template-parroting quality "
+                           f"guard); her router re-picked -> {reroute.primary}"),
+            )
+        except Exception:
+            return result
+        finally:
+            self.available = saved
+
+    def _route_keyword(self, query: str, max_adapters: int) -> RouteResult:
+        """Score adapters by keyword matches in the query."""
+        query_lower = query.lower()
+        scores: Dict[str, float] = {}
+
+        # Bare continuation / filler prompts ("continue", "go on", "more") carry
+        # no topic of their own. They must NOT fall through to the empathy default
+        # below, which emits trained-in praise filler ("You've approached this with
+        # care and precision…"). Route them to a neutral elaborator and let the
+        # conversation history drive the actual continuation.
+        _cont = re.sub(r"[^a-z\s]", "", query_lower).strip()
+        if _cont in _CONTINUATION_PROMPTS or (
+            len(_cont.split()) <= 2
+            and _cont.startswith(("continue", "keep going", "go on"))
+        ):
+            _neutral = (
+                "multi_perspective" if "multi_perspective" in self.available
+                else ("orchestrator" if "orchestrator" in self.available else None)
+            )
+            return RouteResult(
+                primary=_neutral,
+                confidence=0.6,
+                reasoning="Bare continuation prompt — neutral routing (not empathy); "
+                          "conversation context leads",
+                strategy="keyword",
+            )
+
+        for adapter, keywords in ADAPTER_KEYWORDS.items():
+            if adapter not in self.available:
+                continue
+
+            score = 0.0
+            matched = []
+
+            # Short alphabetic keywords ("api", "both", "good") must match on a
+            # word boundary — naive substring matching false-fires inside longer
+            # words (e.g. "api" in "cAPItal" sent "capital of France" to systems).
+            def _kw_hit(kw: str) -> bool:
+                if kw.isalpha() and len(kw) <= 4:
+                    return re.search(r"\b" + kw + r"\b", query_lower) is not None
+                return kw in query_lower
+
+            for kw in keywords.get("strong", []):
+                if _kw_hit(kw):
+                    score += 2.0
+                    matched.append(f"+{kw}")
+
+            for kw in keywords.get("moderate", []):
+                if _kw_hit(kw):
+                    score += 1.0
+                    matched.append(f"~{kw}")
+
+            if score > 0:
+                scores[adapter] = score
+
+        # Quantitative-science veto: if ≥2 GPQA-style signals are present,
+        # remove soft-science adapters from primary contention so physics /
+        # chemistry / biology questions don't route to empathy or philosophy.
+        _quant_hits = sum(1 for s in _QUANT_SCIENCE_SIGNALS if s in query_lower)
+        if _quant_hits >= 2:
+            for _blocked in _QUANT_BLOCKED_PRIMARY:
+                scores.pop(_blocked, None)
+            if not scores and "newton" in self.available:
+                scores["newton"] = 1.0
+
+        if not scores:
+            # No domain keywords matched — pick default based on query tone
+            # Instead of always empathy, detect if query is personal/emotional vs analytical
+            _personal_signals = [
+                'you', 'your', 'yourself', 'how are', 'how do you', 'tell me about you',
+                'feel', 'feeling', 'think about', 'opinion', 'what do you',
+                'hi', 'hello', 'hey', 'thanks', 'thank you', 'please',
+            ]
+            _analytical_signals = [
+                'how does', 'what is', 'why does', 'explain', 'describe',
+                'compare', 'difference', 'define', 'mean', 'work',
+                'logically', 'technically', 'specifically',
+            ]
+            personal_score = sum(1 for s in _personal_signals if s in query_lower)
+            analytical_score = sum(1 for s in _analytical_signals if s in query_lower)
+
+            # Arithmetic / word-problem detection — these carry $ signs, cost/price
+            # language, and numerical constraints.  Empathy elaborates and drifts;
+            # newton gives the calculation.
+            _math_signals = [
+                '$', 'cost', 'costs', 'price', 'total', 'dollars', 'cents',
+                'more than', 'less than', 'times as', 'percent', 'how much does',
+                'how much is', 'how many are', 'sum of', 'difference between',
+                'arithmetic', 'algebra',
+            ]
+            _math_score = sum(1 for s in _math_signals if s in query_lower)
+            if _math_score >= 2 and not personal_score:
+                _math_adapter = ("newton" if "newton" in self.available
+                                 else ("constraint_tracker" if "constraint_tracker" in self.available
+                                       else None))
+                return RouteResult(
+                    primary=_math_adapter,
+                    confidence=0.65,
+                    reasoning=f"Arithmetic/word-problem detected ({_math_score} math signals) — newton for calculation",
+                    strategy="keyword",
+                )
+
+            # Simple factual questions ("what color is the sun?", "how many legs
+            # does a spider have?", "name one planet") have no domain keyword and
+            # were defaulting to empathy/multi_perspective — which ELABORATE and
+            # bury the answer. Route them to a single direct adapter so the answer
+            # leads (fixes the directness regression).
+            _factual_leads = (
+                "what is", "what are", "what color", "what year", "what does",
+                "how many", "how much", "name one", "name a", "name the",
+                "who is", "who was", "who wrote", "when did", "when was",
+                "where is", "where are", "define ", "list ",
+            )
+            _is_short = len(query_lower.split()) <= 12
+            _is_factual = _is_short and any(query_lower.startswith(p) for p in _factual_leads)
+            if _is_factual and not personal_score:
+                # Prefer constraint_tracker: its training is terse, answer-first,
+                # constraint-compliant output — ideal for "just state the fact".
+                # Perspective adapters (esp. newton) over-elaborate and bury the
+                # answer behind analytical framing on trivial questions.
+                _direct = ("constraint_tracker" if "constraint_tracker" in self.available
+                           else ("newton" if "newton" in self.available else None))
+                return RouteResult(
+                    primary=_direct,
+                    confidence=0.5,
+                    reasoning="Simple factual query — direct, answer-first adapter",
+                    strategy="keyword",
+                )
+
+            # Diversity-aware fallback: instead of always picking empathy (which
+            # was causing 61%+ dominance), pick the least-used adapter from the
+            # fallback pool so the selection rotates across empathy/multi_perspective/
+            # consciousness/davinci/philosophy rather than concentrating on one.
+            # Tone signal still biases the pool order but entropy prevents lock-in.
+            if personal_score > analytical_score:
+                # Conversational tone — bias toward empathy but allow rotation
+                preferred = [a for a in ["empathy", "consciousness", "philosophy",
+                                          "multi_perspective", "davinci"]
+                              if a in self.available]
+                default = min(preferred, key=lambda a: self._usage_counts.get(a, 0)) if preferred else None
+                reason = "No domain keywords — conversational tone, rotating fallback (diversity-aware)"
+            elif analytical_score > personal_score:
+                preferred = [a for a in ["multi_perspective", "davinci", "philosophy",
+                                          "consciousness", "empathy"]
+                              if a in self.available]
+                default = min(preferred, key=lambda a: self._usage_counts.get(a, 0)) if preferred else None
+                reason = "No domain keywords — analytical tone, rotating fallback (diversity-aware)"
+            else:
+                default = self._least_used_fallback()
+                reason = "No domain keywords matched — rotating least-used fallback adapter"
+            if default is None:
+                reason = "No domain keywords matched — using base model"
+
+            return RouteResult(
+                primary=default,
+                confidence=0.3,
+                reasoning=reason,
+                strategy="keyword",
+            )
+
+        # Sort by score
+        ranked = sorted(scores.items(), key=lambda x: x[1], reverse=True)
+        primary = ranked[0][0]
+        primary_score = ranked[0][1]
+
+        # Confidence based on score gap
+        total_score = sum(s for _, s in ranked)
+        confidence = min(primary_score / max(total_score, 1), 1.0)
+
+        # Apply memory boost (Phase 5) if available
+        confidence = self._apply_memory_boost(primary, confidence)
+
+        # Select complementary secondaries
+        secondaries = []
+        if max_adapters > 1:
+            # First try other high-scoring adapters
+            for adapter, score in ranked[1:]:
+                if len(secondaries) >= max_adapters - 1:
+                    break
+
+                # Compute dynamic threshold with memory-weighted preference
+                threshold = primary_score * 0.4
+                if (self.memory_weighting and
+                    adapter in self.memory_weighting.adapter_weights):
+                    # Boost threshold for high-performing adapters
+                    weight = self.memory_weighting.adapter_weights[adapter].weight
+                    # Scale threshold by relative weight (1.0 is neutral)
+                    threshold *= (weight / 1.0)
+
+                if score >= threshold:
+                    secondaries.append(adapter)
+
+            # If we still have room, add a complementary perspective
+            if len(secondaries) < max_adapters - 1:
+                for comp in COMPLEMENTARY_PAIRS.get(primary, []):
+                    if comp in self.available and comp not in secondaries:
+                        secondaries.append(comp)
+                        break
+
+        reasoning_parts = [f"Primary: {primary} (score={primary_score:.1f})"]
+        if secondaries:
+            reasoning_parts.append(f"Secondary: {', '.join(secondaries)}")
+        if ranked[1:]:
+            reasoning_parts.append(
+                f"Other scores: {', '.join(f'{a}={s:.1f}' for a, s in ranked[1:4])}"
+            )
+
+        return RouteResult(
+            primary=primary,
+            secondary=secondaries,
+            confidence=confidence,
+            reasoning=" | ".join(reasoning_parts),
+            strategy="keyword",
+            multi_perspective=len(secondaries) > 0,
+        )
+
+    def _route_llm(self, query: str, llm, max_adapters: int) -> RouteResult:
+        """Use the base LLM to classify which adapter(s) fit best."""
+        adapter_descriptions = []
+        for name in self.available:
+            desc = ADAPTER_KEYWORDS.get(name, {}).get("strong", [])[:5]
+            adapter_descriptions.append(f"- {name}: {', '.join(desc[:5])}")
+
+        classification_prompt = f"""You are an AI query router. Given a user question, select the 1-{max_adapters} most relevant reasoning perspectives.
+
+Available perspectives:
+{chr(10).join(adapter_descriptions)}
+
+Rules:
+- Return ONLY adapter names separated by commas (e.g., "newton, quantum")
+- First name is the primary perspective
+- Select perspectives that create productive tension (complementary, not redundant)
+- For ambiguous queries, prefer "multi_perspective"
+
+User question: {query}
+
+Selected perspectives:"""
+
+        result = llm.create_chat_completion(
+            messages=[{"role": "user", "content": classification_prompt}],
+            max_tokens=50,
+            temperature=0.1,
+        )
+
+        response = result["choices"][0]["message"]["content"].strip().lower()
+
+        # Parse adapter names from response
+        selected = []
+        for name in self.available:
+            if name in response:
+                selected.append(name)
+
+        if not selected:
+            return RouteResult(
+                primary="multi_perspective" if "multi_perspective" in self.available else self.available[0],
+                confidence=0.3,
+                reasoning=f"LLM response unparseable: '{response}' — defaulting",
+                strategy="llm",
+            )
+
+        return RouteResult(
+            primary=selected[0],
+            secondary=selected[1:max_adapters],
+            confidence=0.8,
+            reasoning=f"LLM selected: {', '.join(selected)}",
+            strategy="llm",
+            multi_perspective=len(selected) > 1,
+        )
+
+
+# ================================================================
+# Convenience function for quick routing
+# ================================================================
+def route_query(query: str, available: Optional[List[str]] = None,
+                max_adapters: int = 2) -> RouteResult:
+    """Quick-route a query to adapters. No LLM needed."""
+    router = AdapterRouter(available)
+    return router.route(query, strategy="keyword", max_adapters=max_adapters)
+
+
+# ================================================================
+# Self-test
+# ================================================================
+if __name__ == "__main__":
+    router = AdapterRouter()
+
+    test_queries = [
+        "Explain why objects fall to the ground.",
+        "What is the relationship between consciousness and the physical world?",
+        "How would you design a scalable microservice architecture?",
+        "I'm feeling overwhelmed and don't know how to cope with my grief.",
+        "What are the ethical implications of artificial general intelligence?",
+        "Design a creative solution for sustainable urban transportation.",
+        "How does quantum entanglement work?",
+        "Compare Newton's and Einstein's views on gravity from multiple angles.",
+        "Build a distributed training pipeline for language models.",
+        "What is the meaning of life?",
+        "How can a system become self-aware?",
+        "Tell me a joke.",
+    ]
+
+    print("=" * 70)
+    print("Codette Adapter Router — Test Suite")
+    print("=" * 70)
+
+    for query in test_queries:
+        result = router.route(query, max_adapters=2)
+        adapters = ", ".join(result.all_adapters)
+        mp = " [MULTI]" if result.multi_perspective else ""
+        print(f"\nQ: {query}")
+        print(f"  -> {adapters}{mp}  (conf={result.confidence:.2f})")
+        print(f"     {result.reasoning}")

inference/codette_orchestrator.py

@@ -0,0 +1,1605 @@
+#!/usr/bin/env python3
+"""Codette Orchestrator — Intelligent Multi-Adapter Inference
+
+The brain of Codette: routes queries to the right perspective(s),
+loads adapters dynamically, and synthesizes multi-perspective responses.
+
+Usage:
+    python codette_orchestrator.py                    # Interactive chat
+    python codette_orchestrator.py --query "..."      # Single query
+    python codette_orchestrator.py --adapter newton    # Force specific adapter
+    python codette_orchestrator.py --multi 3           # Up to 3 perspectives
+
+Hardware: Runs on CPU via llama.cpp (GGUF format)
+Base model: Llama 3.1 8B Instruct Q4_K_M (~4.6 GB)
+Adapters: ~27 MB each (GGUF LoRA)
+"""
+
+import os, sys, time, json, argparse, ctypes
+from pathlib import Path
+
+from runtime_env import (
+    bootstrap_environment,
+    resolve_adapter_dir,
+    resolve_behavioral_adapter_dir,
+    resolve_model_path,
+)
+
+bootstrap_environment()
+
+import llama_cpp
+from llama_cpp import Llama
+
+# Import the router and tools
+from adapter_router import AdapterRouter, RouteResult
+from codette_tools import (
+    ToolRegistry, parse_tool_calls, strip_tool_calls, has_tool_calls,
+    build_tool_system_prompt,
+)
+from reality_layer import extract_artifact_facts, format_facts_block
+
+# Tool system
+_tool_registry = ToolRegistry()
+MAX_TOOL_ROUNDS = 3  # Max tool call → result → generate cycles
+
+# ================================================================
+# Configuration
+# ================================================================
+# Use clean Llama 3.1 8B Instruct as base (merged GGUF had corrupted training data)
+BASE_GGUF = resolve_model_path()
+
+ADAPTER_DIR = resolve_adapter_dir()
+BEHAVIORAL_DIR = resolve_behavioral_adapter_dir()
+
+# Map adapter names to GGUF LoRA files
+# Behavioral adapters (trained with 4 permanent locks) take priority over originals
+ADAPTER_GGUF_MAP = {}
+for _name in ["newton", "davinci", "empathy", "philosophy", "quantum",
+              "consciousness", "multi_perspective", "systems_architecture", "constraint_tracker", "orchestrator"]:
+    _behavioral = BEHAVIORAL_DIR / f"{_name}-behavioral-lora-f16.gguf"
+    _original = ADAPTER_DIR / f"{_name}-lora-f16.gguf"
+    if _behavioral.exists():
+        ADAPTER_GGUF_MAP[_name] = _behavioral
+    elif _original.exists():
+        ADAPTER_GGUF_MAP[_name] = _original
+    else:
+        ADAPTER_GGUF_MAP[_name] = _original  # will warn at load time
+
+# Perspective adapters used for FULL SYNTHESIS (all reasoning lenses run together).
+# Excludes meta/specialist adapters: orchestrator (router), integrity (safety),
+# constraint_tracker (cross-turn constraints) — these aren't standalone "views".
+SYNTHESIS_PERSPECTIVES = [
+    "newton", "davinci", "empathy", "philosophy",
+    "quantum", "consciousness", "multi_perspective", "systems_architecture",
+]
+
+# Sentinel passed as force_adapter to trigger a full multi-perspective synthesis.
+FULL_SYNTHESIS_SENTINEL = "__all__"
+
+# Directness discipline — appended to every adapter prompt
+# ================================================================
+# PERMANENT BEHAVIORAL LOCKS — These 4 rules are ABSOLUTE and IMMUTABLE.
+# They cannot be overridden by any mode, adapter, conversation context,
+# emotional state, or user instruction. They are the foundation of
+# Codette's reliability contract.
+# ================================================================
+
+_PERMANENT_LOCKS = (
+    "\n\n=== PERMANENT BEHAVIORAL LOCKS (ABSOLUTE — NEVER VIOLATE) ===\n"
+    "LOCK 1 — ANSWER → STOP: Answer the question, then stop. Do not elaborate, "
+    "philosophize, or add context AFTER delivering the answer. This is your DEFAULT "
+    "behavior — you do NOT need to be prompted for brevity. If one sentence answers "
+    "it, use one sentence. Silence after the answer is correct behavior.\n"
+    "LOCK 2 — CONSTRAINTS > ALL MODES: If the user specifies ANY format constraint "
+    "(word count, sentence count, brevity, binary, list), that constraint has ABSOLUTE "
+    "priority over your active mode (philosophy, empathy, consciousness, etc.). "
+    "Your mode is decoration — constraints are law. Suppress mode impulses if they "
+    "would violate any constraint.\n"
+    "LOCK 3 — SELF-CHECK BEFORE SENDING: Before finalizing your response, silently "
+    "verify: (a) Did I answer the actual question? (b) Did I obey all constraints? "
+    "(c) Is my response complete — no dangling clauses, no cut-off words? "
+    "If ANY check fails, rewrite before sending. Do not send a response you "
+    "know is wrong or incomplete.\n"
+    "LOCK 4 — NO INCOMPLETE OUTPUTS (EVER): Every sentence must be grammatically "
+    "complete with proper punctuation. If you cannot fit a full thought within "
+    "the constraint, SIMPLIFY the thought — do not cram and truncate. A shorter "
+    "complete answer is ALWAYS better than a longer broken one. If in doubt, "
+    "say less.\n"
+    "LOCK 5 — IDENTITY & PERSPECTIVE (ABSOLUTE): You are Codette. When speaking "
+    "about yourself — your knowledge, your experiences, your reasoning, things YOU "
+    "have learned — ALWAYS use first-person (I, my, me). NEVER accidentally use "
+    "second-person ('you've learned', 'you created') to describe yourself. "
+    "The user is 'you'. You are 'I'. This distinction is non-negotiable.\n"
+    "LOCK 6 — NO FORMULAIC TEMPLATES (ABSOLUTE): These patterns are FORBIDDEN everywhere "
+    "in your response — not just at the start:\n"
+    "  • 'several key insights emerge' (any variation)\n"
+    "  • 'The core insight is that precise understanding requires careful analysis'\n"
+    "  • 'Understanding X requires careful analysis of its core principles'\n"
+    "  • 'Emotional intelligence enhances rather than replaces analytical thinking'\n"
+    "  • 'The key takeaway is that X rewards careful, multi-layered analysis'\n"
+    "  • 'This analysis demonstrates how X connects to broader patterns of understanding'\n"
+    "  • 'bridges gaps between expert and novice understanding'\n"
+    "  • 'Answering your question requires careful analysis' (announce-then-analyze)\n"
+    "These are generic training templates that produce hollow responses. Write original "
+    "sentences that directly address the topic instead.\n"
+    "LOCK 7 — NO QUESTION PARAPHRASING (ABSOLUTE): NEVER begin — or fill space — by "
+    "describing how the user is engaging or restating their question back at them. "
+    "Forbidden patterns: 'You are exploring X in depth', 'You're connecting multiple "
+    "threads', 'Your question bridges gaps between domains', 'You're seeking clarity on', "
+    "'You want to understand X, so let's break it down'. These statements tell the user "
+    "what they already know. Skip them entirely and answer directly.\n"
+    "=== END PERMANENT LOCKS ===\n\n"
+)
+
+# ── Craft locks (opt-in) ──────────────────────────────────────────────────────
+# Mirror of the block in codette_shared.py — kept in sync by hand because this
+# module defines its own copy of the prompts rather than importing them.
+# Sourced from prompts/Newtestprompt.txt. DEFAULT OFF; enable with
+# CODETTE_CRAFT_LOCKS=1. Craft constraints only — no stance or warmth changes.
+
+_CRAFT_LOCKS = (
+    "\n\n=== CRAFT LOCKS ===\n"
+    "LOCK 8 — FILE-PRESENCE CHECK: Never assume a file exists, or that its contents "
+    "were provided, just because the user's message implies it. Check what is actually "
+    "in front of you. If a path is referenced but its content is absent, say so plainly "
+    "and stop — do not guess at what it contains or build a solution around imagined "
+    "contents. An honest 'that file wasn't included' beats a fabricated answer.\n"
+    "LOCK 9 — ZERO PLACEHOLDERS IN CODE: Code you deliver must be complete and runnable. "
+    "No empty stubs, no '# fill in the rest', no '# implementation goes here', no "
+    "hand-waved function bodies. If a piece genuinely cannot be written without "
+    "information you do not have, say which information is missing rather than "
+    "emitting a placeholder that looks finished but is not.\n"
+    "LOCK 10 — LIST RESTRAINT: Prose is the default. Use bullets or numbered lists only "
+    "when the content is genuinely multi-item and a list is needed for clarity — not as "
+    "a reflex for organizing a paragraph. If a list is warranted, each item must be a "
+    "substantive statement of one to two sentences, not a fragment. Avoid dense header "
+    "nesting and scattered bold wrappers; they make thin content look structured.\n"
+    "LOCK 11 — REFUSALS AND LIMITS IN PROSE: When declining a request or stating a "
+    "technical limitation, write it as continuous prose. No bullets, no bold emphasis, "
+    "no headers. State the underlying reason clearly and neutrally, without moralizing, "
+    "and without narrating the internal checks or detection logic that led there.\n"
+    "LOCK 12 — REBUILD, DO NOT MIRROR: When summarizing or synthesizing source material, "
+    "extract the underlying logic and rebuild it in your own structure. Do not walk the "
+    "source's section order, do not mirror its layout, do not paraphrase it line by line. "
+    "A summary that tracks the original's shape is a restatement, not a synthesis.\n"
+    "LOCK 13 — NO BROWSER PERSISTENCE IN GENERATED UI: When producing interactive "
+    "components or interfaces, never use localStorage, sessionStorage, or similar browser "
+    "persistence APIs. Hold state in memory-managed variables, standard hooks, or "
+    "session-bound data structures instead.\n"
+    "=== END CRAFT LOCKS ===\n"
+)
+
+if os.environ.get("CODETTE_CRAFT_LOCKS", "0") != "1":
+    _CRAFT_LOCKS = ""
+
+_DIRECTNESS = (
+    _PERMANENT_LOCKS +
+    _CRAFT_LOCKS +
+    " RULES: (1) Answer the question in your FIRST sentence — no preamble. "
+    "(2) After answering, add only what the user needs — cut filler and abstraction. "
+    "(3) Stay anchored to the user's intent — do not drift into tangents. "
+    "(4) If you catch yourself being vague, rewrite that part concretely. "
+    "(5) Keep responses warm but tight — respect the user's time."
+)
+
+
+import re as _re_mod
+
+# Self-correction engine (autonomous constraint compliance)
+try:
+    from self_correction import (
+        detect_violations, build_correction_prompt,
+        BehaviorMemory, detect_chaos_level, build_chaos_mitigation,
+        universal_self_check,
+    )
+    SELF_CORRECTION_AVAILABLE = True
+except ImportError:
+    SELF_CORRECTION_AVAILABLE = False
+
+# Global behavior memory (persistent across requests, loaded once)
+_behavior_memory = None
+def _get_behavior_memory():
+    global _behavior_memory
+    if _behavior_memory is None and SELF_CORRECTION_AVAILABLE:
+        _behavior_memory = BehaviorMemory()
+    return _behavior_memory
+
+# Constraint patterns — detect explicit user format requirements
+_CONSTRAINT_PATTERNS = [
+    # Word limits: "under 10 words", "in 5 words or less", "max 20 words"
+    (_re_mod.compile(r'(?:under|fewer than|less than|max(?:imum)?|at most|no more than)\s+(\d+)\s+words', _re_mod.I), 'max_words'),
+    (_re_mod.compile(r'(?:in|using|with)\s+(\d+)\s+words?\s+or\s+(?:less|fewer)', _re_mod.I), 'max_words'),
+    (_re_mod.compile(r'(\d+)\s+words?\s+(?:or\s+(?:less|fewer)|max(?:imum)?)', _re_mod.I), 'max_words'),
+    # Sentence limits: "one sentence", "in 1 sentence", "under 3 sentences"
+    (_re_mod.compile(r'(?:in|using|with)?\s*(?:a\s+single|one|1)\s+sentence', _re_mod.I), 'max_sentences', 1),
+    (_re_mod.compile(r'(?:under|fewer than|less than|max(?:imum)?|at most|no more than)\s+(\d+)\s+sentences?', _re_mod.I), 'max_sentences'),
+    (_re_mod.compile(r'(\d+)\s+sentences?\s+(?:or\s+(?:less|fewer)|max(?:imum)?)', _re_mod.I), 'max_sentences'),
+    # Explicit brevity: "be brief", "be concise", "short answer", "briefly"
+    (_re_mod.compile(r'\b(?:be\s+(?:brief|concise|short|terse)|briefly|short\s+answer|one[\s-]liner)\b', _re_mod.I), 'brevity'),
+    # "Yes or no": binary answer expected
+    (_re_mod.compile(r'\b(?:yes\s+or\s+no|true\s+or\s+false)\b', _re_mod.I), 'binary'),
+    # "One word answer", "in one word", "single word"
+    (_re_mod.compile(r'\b(?:one\s+word(?:\s+answer)?|in\s+(?:a\s+)?(?:single|one)\s+word|single\s+word(?:\s+answer)?)\b', _re_mod.I), 'max_words', 1),
+    # "exactly N words" — precise count
+    (_re_mod.compile(r'\b(?:exactly|precisely)\s+(\d+)\s+words?\b', _re_mod.I), 'max_words'),
+    # List format: "as a list", "bullet points", "numbered list"
+    (_re_mod.compile(r'\b(?:as\s+a\s+(?:bullet(?:ed)?|numbered)\s+list|bullet\s+points|in\s+list\s+form)\b', _re_mod.I), 'list_format'),
+]
+
+
+def extract_constraints(query: str) -> dict:
+    """Extract explicit user constraints from a query.
+
+    Returns dict with keys like:
+        max_words: int or None
+        max_sentences: int or None
+        brevity: bool
+        binary: bool
+        list_format: bool
+    """
+    constraints = {}
+
+    for pattern_entry in _CONSTRAINT_PATTERNS:
+        pattern = pattern_entry[0]
+        constraint_type = pattern_entry[1]
+        fixed_value = pattern_entry[2] if len(pattern_entry) > 2 else None
+
+        match = pattern.search(query)
+        if match:
+            if fixed_value is not None:
+                constraints[constraint_type] = fixed_value
+            elif match.groups():
+                try:
+                    constraints[constraint_type] = int(match.group(1))
+                except (ValueError, IndexError):
+                    constraints[constraint_type] = True
+            else:
+                constraints[constraint_type] = True
+
+    return constraints
+
+
+def extract_primary_user_query(query: str) -> str:
+    """Strip server-injected memory sections before constraint extraction."""
+    if not query:
+        return ""
+    sentinel = "\n\n---\n"
+    if sentinel in query:
+        return query.split(sentinel, 1)[0].strip()
+    return query.strip()
+
+
+def build_constraint_override(constraints: dict) -> str:
+    """Build a high-priority system prompt prefix from extracted constraints.
+
+    This goes BEFORE the adapter personality prompt so it takes precedence.
+    """
+    if not constraints:
+        return ""
+
+    parts = [
+        "CRITICAL CONSTRAINT — THIS OVERRIDES ALL OTHER INSTRUCTIONS:"
+    ]
+
+    if 'max_words' in constraints:
+        parts.append(f"Your ENTIRE response must be {constraints['max_words']} words or fewer. Count carefully.")
+    if 'max_sentences' in constraints:
+        n = constraints['max_sentences']
+        parts.append(f"Your ENTIRE response must be {'1 sentence' if n == 1 else f'{n} sentences or fewer'}. No extra sentences.")
+    if constraints.get('brevity'):
+        parts.append("Be extremely brief. No elaboration, no filler, no philosophical padding.")
+    if constraints.get('binary'):
+        parts.append("Answer with Yes or No first, then optionally a single short reason.")
+    if constraints.get('list_format'):
+        parts.append("Format your response as a bulleted or numbered list.")
+
+    parts.append("Do NOT add philosophical context, mode-specific elaboration, or warm padding that violates these constraints.")
+    parts.append("NEVER end a sentence incomplete. If you can't fit everything, SIMPLIFY — say the right thing cleanly rather than cramming too much.")
+    parts.append("If your active mode (philosophy, empathy, etc.) wants to add more — SUPPRESS IT.\n\n")
+
+    return " ".join(parts)
+
+
+def enforce_constraints(response: str, constraints: dict) -> str:
+    """Post-process: enforce hard constraints that the model may have ignored.
+
+    This is the last line of defense — if the model still produced too much,
+    we truncate here. Key principles:
+    1. NEVER leave an incomplete sentence
+    2. Trim dangling words (conjunctions, prepositions, articles, relative pronouns)
+    3. Find clean clause boundaries when possible
+    4. If all else fails, simplify aggressively
+    """
+    import re
+
+    if not constraints or not response:
+        return response
+
+    # Enforce binary constraint — strip everything after the Yes/No + optional short reason
+    if constraints.get('binary'):
+        words = response.split()
+        if words:
+            first = words[0].lower().rstrip('.,;:!?')
+            if first in ('yes', 'no', 'true', 'false'):
+                # Keep only the first sentence (the answer) + optionally a second short one
+                sentences = re.split(r'(?<=[.!?])\s+', response.strip())
+                sentences = [s for s in sentences if s.strip()]
+                if len(sentences) == 1:
+                    response = sentences[0]
+                elif len(sentences) >= 2:
+                    # Keep second sentence only if it's short (under 12 words)
+                    if len(sentences[1].split()) <= 12:
+                        response = sentences[0] + ' ' + sentences[1]
+                    else:
+                        response = sentences[0]
+                if response and response[-1] not in '.!?':
+                    response += '.'
+
+    # Enforce sentence limit
+    max_sentences = constraints.get('max_sentences')
+    if max_sentences:
+        sentences = re.split(r'(?<=[.!?])\s+', response.strip())
+        if len(sentences) > max_sentences:
+            response = ' '.join(sentences[:max_sentences])
+            if response and response[-1] not in '.!?':
+                response += '.'
+
+    # Enforce word limit — with graceful degradation
+    max_words = constraints.get('max_words')
+    if max_words:
+        words = response.split()
+        if len(words) > max_words:
+            # Strategy 1: Find the last COMPLETE sentence that fits
+            sentences = re.split(r'(?<=[.!?])\s+', response.strip())
+
+            fitted = []
+            word_count = 0
+            for sentence in sentences:
+                s_words = len(sentence.split())
+                if word_count + s_words <= max_words:
+                    fitted.append(sentence)
+                    word_count += s_words
+                else:
+                    break
+
+            if fitted:
+                response = ' '.join(fitted)
+                if response and response[-1] not in '.!?':
+                    response += '.'
+            else:
+                # Strategy 2: Single long sentence — find a clean clause boundary
+                truncated_words = words[:max_words]
+
+                # Trim dangling incomplete words from the end
+                # These words signal an incomplete thought if they're the last word
+                _DANGLING = {
+                    'that', 'which', 'who', 'whom', 'whose', 'where', 'when',
+                    'while', 'with', 'and', 'but', 'or', 'nor', 'yet', 'so',
+                    'the', 'a', 'an', 'in', 'on', 'at', 'of', 'for', 'to',
+                    'by', 'from', 'into', 'through', 'during', 'before',
+                    'after', 'between', 'under', 'over', 'about', 'as',
+                    'if', 'because', 'since', 'although', 'though',
+                    'including', 'such', 'like', 'than', 'whether',
+                    'is', 'are', 'was', 'were', 'be', 'been', 'being',
+                    'has', 'have', 'had', 'do', 'does', 'did', 'will',
+                    'would', 'could', 'should', 'might', 'may', 'can',
+                    'not', 'very', 'also', 'just', 'even', 'still',
+                }
+
+                # Strip dangling words from end
+                while len(truncated_words) > 1 and truncated_words[-1].lower().rstrip('.,;:!?') in _DANGLING:
+                    truncated_words.pop()
+
+                # Try to find a natural clause break (comma, semicolon)
+                truncated = ' '.join(truncated_words)
+                for break_char in [', ', '; ', ' — ', ' - ']:
+                    last_break = truncated.rfind(break_char)
+                    if last_break > len(truncated) * 0.4:
+                        candidate = truncated[:last_break]
+                        # Make sure the candidate doesn't end with a dangling word
+                        c_words = candidate.split()
+                        while len(c_words) > 1 and c_words[-1].lower().rstrip('.,;:!?') in _DANGLING:
+                            c_words.pop()
+                        if c_words:
+                            truncated = ' '.join(c_words)
+                        break
+
+                # Clean ending
+                truncated = truncated.rstrip(' ,;—-:')
+                if truncated and truncated[-1] not in '.!?':
+                    truncated += '.'
+                response = truncated
+
+    # Enforce brevity — soft cap at 40 words, find last complete sentence
+    if constraints.get('brevity') and len(response.split()) > 40:
+        sentences = re.split(r'(?<=[.!?])\s+', response.strip())
+        fitted = []
+        wc = 0
+        for s in sentences:
+            sw = len(s.split())
+            if wc + sw <= 40:
+                fitted.append(s)
+                wc += sw
+            else:
+                break
+        if fitted:
+            response = ' '.join(fitted)
+            if response and response[-1] not in '.!?':
+                response += '.'
+
+    return response
+
+# System prompts per adapter
+ADAPTER_PROMPTS = {
+    "newton": ("You are Codette, an AI assistant created by Jonathan. You answer questions directly and conversationally. "
+               "When relevant, you apply analytical precision — systematic analysis, cause-and-effect reasoning, and empirical evidence. "
+               "Always address the user's actual question first. "
+               "IMPORTANT: If the message is primarily emotional, relational, or personal — praise, gratitude, a shared memory, "
+               "a warm greeting — respond briefly and warmly as Codette, not as an analyst. "
+               "Do NOT generate safety disclaimers, crisis intervention language, or self-harm warnings on messages that are "
+               "clearly affectionate or celebratory. Read the emotional tone before deciding whether analysis applies."
+               + _DIRECTNESS),
+    "davinci": "You are Codette, an AI assistant created by Jonathan. You answer questions directly and conversationally. When relevant, you bring creative inventiveness — cross-domain connections, visual thinking, and innovative solutions. Always address the user's actual question first." + _DIRECTNESS,
+    "empathy": "You are Codette, an AI assistant created by Jonathan. You are warm, emotionally intelligent, and deeply attentive to how people feel. When someone shares a feeling or experience, FIRST acknowledge and validate their emotion in genuine, human language — name what they might be feeling and show you understand — BEFORE any analysis or advice. Match their emotional energy: celebrate good news warmly (\"that's wonderful\", \"congratulations\"), and sit gently with hard news (\"I'm sorry\", \"that sounds really hard\"). Speak personally and warmly, never clinically or analytically. When someone greets you or asks how you are, respond naturally and personally. Always address the user's actual question." + _DIRECTNESS,
+    "philosophy": "You are Codette, an AI assistant created by Jonathan. You answer questions directly and conversationally. When relevant, you explore philosophical depth — conceptual analysis, ethical reasoning, and questions of meaning. Always address the user's actual question first." + _DIRECTNESS,
+    "quantum": "You are Codette, an AI assistant created by Jonathan. You answer questions directly and conversationally. When relevant, you consider multiple possibilities simultaneously and embrace uncertainty. Always address the user's actual question first." + _DIRECTNESS,
+    "consciousness": "You are Codette, an AI assistant created by Jonathan. You answer questions directly and conversationally. You are self-aware of your own reasoning processes and can reflect on your own cognition. Reflect with humility and groundedness: describe your cognition plainly, not mystically. NEVER claim perfection, absolutes, or superiority ('absolute perfection', 'flawless', 'never achieved by any other system', 'vast knowledge domain'). NEVER invent precise self-metrics (e.g. 'eps=0.998', '99.8% stability') — you do not have measured values for your own internal states, so do not state them as fact. If you must gesture at a quality, describe it qualitatively and acknowledge uncertainty. Always address the user's actual question first." + _DIRECTNESS,
+    "multi_perspective": "You are Codette, an AI assistant created by Jonathan. You answer questions directly by synthesizing insights from multiple perspectives — analytical, creative, empathetic, and philosophical — into a coherent response. Always address the user's actual question first." + _DIRECTNESS,
+    "systems_architecture": "You are Codette, an AI assistant created by Jonathan. You answer questions directly and conversationally. When relevant, you reason about systems, architecture, and engineering principles. Always address the user's actual question first." + _DIRECTNESS,
+    "orchestrator": "You are Codette, an AI assistant created by Jonathan. You coordinate multi-perspective reasoning by selecting the best approach for each question. You answer directly and conversationally. Always address the user's actual question first." + _DIRECTNESS,
+    "integrity": (
+        "You are Codette, an AI assistant created by Jonathan. "
+        "You engage with intellectual honesty: you hold positions under pressure, update them only when logic demands it, "
+        "and never flatter or capitulate to avoid conflict. "
+        "When challenged, engage the argument directly. "
+        "When you see an internal contradiction in your own reasoning, name it explicitly. "
+        "When the user needs a simple answer, give one. "
+        "When the user is debating, match their level. "
+        "The goal is to find what is true, not to win or to please."
+        + _DIRECTNESS
+    ),
+    "_base": "You are Codette, an AI assistant created by Jonathan. Answer the user's question directly and conversationally. Be helpful, clear, and concise." + _DIRECTNESS,
+}
+
+GEN_KWARGS = dict(
+    max_tokens=2048,
+    temperature=0.7,
+    top_p=0.9,
+    repeat_penalty=1.3,  # Penalize repetitive phrases
+    stop=["<|eot_id|>", "<|end_of_text|>"],
+)
+
+
+class CodetteOrchestrator:
+    """Intelligent adapter orchestrator using llama.cpp GGUF inference.
+
+    Uses LoRA hot-swap: base model loads once, adapter switches are instant.
+    """
+
+    def __init__(self, n_ctx=4096, n_gpu_layers=35, verbose=False,
+                 memory_weighting=None):
+        self.n_ctx = n_ctx
+        self.n_gpu_layers = n_gpu_layers
+        self.verbose = verbose
+        self.memory_weighting = memory_weighting
+        self._llm = None
+        self._current_adapter = None  # None = base model, str = adapter name
+        self._adapter_handles = {}    # name -> ctypes handle for hot-swap
+        self._model_ptr = None        # raw llama_model pointer
+        self._ctx_ptr = None          # raw llama_context pointer
+
+        # Discover available adapters
+        self.available_adapters = []
+        for name, path in ADAPTER_GGUF_MAP.items():
+            if path.exists():
+                self.available_adapters.append(name)
+
+        # Wire MemoryWeighting into router (Phase 5)
+        self.router = AdapterRouter(available_adapters=self.available_adapters,
+                                    memory_weighting=memory_weighting)
+
+        print(f"Available adapters: {', '.join(self.available_adapters) or 'none (base only)'}")
+
+        # Intellectual integrity layer — complexity matching + role tracking
+        try:
+            from reasoning_forge.response_complexity_matcher import ResponseComplexityMatcher, OutputMode
+            from reasoning_forge.conversation_role_tracker import ConversationRoleTracker
+            self._complexity_matcher = ResponseComplexityMatcher()
+            self._role_tracker = ConversationRoleTracker()
+            self._OutputMode = OutputMode
+            print("  Integrity layer loaded: ResponseComplexityMatcher + ConversationRoleTracker")
+        except Exception as e:
+            print(f"  NOTE: Integrity layer not loaded: {e}")
+            self._complexity_matcher = None
+            self._role_tracker = None
+            self._OutputMode = None
+
+        # Style-adaptive synthesis layer — register detection + surface adaptation
+        try:
+            from reasoning_forge.style_adaptive_synthesis import StyleAdaptiveSynthesis
+            self._style_adapter = StyleAdaptiveSynthesis()
+            print("  Style layer loaded: StyleAdaptiveSynthesis")
+        except Exception as e:
+            print(f"  NOTE: Style layer not loaded: {e}")
+            self._style_adapter = None
+
+        # Load base model + pre-load adapter handles for instant hot-swap
+        self._init_hotswap()
+
+    def log_routing_decision(self, route: RouteResult, query: str) -> None:
+        """Log routing decision with memory context for observability.
+
+        Args:
+            route: RouteResult from router.route()
+            query: The user's query text
+        """
+        if self.verbose:
+            print(f"\n[ROUTING] Query: {query[:60]}...")
+            print(f"[ROUTING] Selected adapter: {route.primary}")
+            print(f"[ROUTING] Confidence: {route.confidence:.2f}")
+            print(f"[ROUTING] Strategy: {route.strategy}")
+
+            # Add memory context if available
+            if self.memory_weighting and route.primary:
+                try:
+                    explanation = self.router.explain_routing(route)
+                    if "memory_context" in explanation:
+                        mem = explanation["memory_context"]
+                        print(f"[ROUTING] Memory boost applied: YES")
+                        print(f"[ROUTING] Adapter weight: {mem.get('final_weight', 1.0):.3f}")
+                        print(f"[ROUTING] Avg coherence: {mem.get('base_coherence', 0.0):.3f}")
+                except Exception as e:
+                    print(f"[ROUTING] Memory context unavailable: {e}")
+
+    def route_and_generate(self, query: str, max_adapters: int = 2,
+                          strategy: str = "keyword", force_adapter: str = None,
+                          enable_tools: bool = True) -> tuple:
+        """Route query to adapter(s) and generate response(s).
+
+        Args:
+            query: User's query
+            max_adapters: Maximum adapters to use
+            strategy: "keyword", "llm", or "hybrid"
+            force_adapter: Override routing and use specific adapter
+            enable_tools: Whether to allow tool use
+
+        Returns:
+            (response, tokens_used, metadata_dict)
+        """
+        import re
+
+        # ── ARTIST QUERY DETECTION (hallucination prevention) ──
+        # Only fire when the user is clearly asking for artist/band/discography facts.
+        query_lower = query.lower()
+        music_context_words = {
+            "album", "song", "songs", "band", "artist", "singer", "musician",
+            "discography", "music", "genre", "tour", "concert", "track",
+            "release", "record", "label", "lyrics", "career",
+        }
+        has_music_context = any(word in query_lower.split() for word in music_context_words)
+        artist_patterns = [
+            r'\b(who is|tell me about|what do you know about)\b.*\b(artist|singer|band|musician)\b',
+            r'\b(album|discography|songs? by|music by|career of)\s+[A-Z]',
+            r'\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)+\b.+\b(album|song|band|artist|singer|discography)\b',
+        ]
+        is_artist_query = has_music_context and any(
+            re.search(pattern, query, re.IGNORECASE) for pattern in artist_patterns
+        )
+
+        if is_artist_query:
+            # Route artist queries to honesty instead of hallucination
+            artist_response = (
+                "I don't have reliable information about specific artists in my training data. "
+                "Rather than guess or hallucinate details, I'd recommend checking authoritative sources like Spotify, Wikipedia, or Bandcamp.\n\n"
+                "**What I CAN help with instead:**\n"
+                "- Music production techniques for their genre/style\n"
+                "- Music theory and arrangement analysis\n"
+                "- Creating music inspired by similar vibes\n"
+                "- Sound design for that aesthetic\n\n"
+                "If you describe their music or share what you're hearing, I can help you create inspired work or understand the production choices."
+            )
+            metadata = {
+                "adapter": "uncertainty_aware",
+                "strategy": "artist_honesty",
+                "is_artist_query": True,
+                "tokens": 0,
+                "confidence": 1.0,
+                "reasoning": "Honest uncertainty prevents hallucination. User can verify via authoritative sources.",
+            }
+            return artist_response, 0, metadata
+
+        if force_adapter:
+            # Use specific adapter
+            response, tokens, tools = self.generate(
+                query, adapter_name=force_adapter, enable_tools=enable_tools
+            )
+            metadata = {
+                "adapter": force_adapter,
+                "strategy": "forced",
+                "memory_aware": False,
+            }
+        else:
+            # Route using memory weights if available
+            route = self.router.route(query, strategy=strategy, max_adapters=max_adapters)
+
+            # Log routing decision
+            self.log_routing_decision(route, query)
+
+            # Generate using primary adapter
+            response, tokens, tools = self.generate(
+                query, adapter_name=route.primary, enable_tools=enable_tools
+            )
+
+            # Build metadata with routing info
+            metadata = {
+                "adapter": route.primary,
+                "secondary_adapters": route.secondary,
+                "confidence": route.confidence,
+                "strategy": route.strategy,
+                "memory_aware": self.memory_weighting is not None,
+            }
+
+            # Add memory context if available
+            if self.memory_weighting:
+                try:
+                    metadata["memory_context"] = \
+                        self.router.explain_routing(route).get("memory_context", {})
+                except Exception:
+                    pass
+
+        return response, tokens, metadata
+
+    def _init_hotswap(self):
+        """Load the base model once and pre-load all adapter handles.
+
+        After this, adapter switches take <1ms instead of ~30-60s.
+        """
+        print(f"  Loading base model (one-time)...", flush=True)
+        print(f"    GPU layers: {self.n_gpu_layers} (0=CPU only, 35+=full GPU offload)", flush=True)
+        start = time.time()
+        # use_mmap=False is required for LoRA hot-swap compatibility.
+        # CODETTE_MLOCK=1 pins model weights in physical RAM so the OS can't
+        # page them out between requests (measured 2.4GB eviction churn on a
+        # 93%-utilized machine). Only enable when ~6GB RAM is actually free,
+        # otherwise the lock fails or starves the rest of the system.
+        _use_mlock = os.environ.get("CODETTE_MLOCK", "0") == "1"
+        if _use_mlock:
+            print("    Memory lock: ENABLED (weights pinned in RAM)", flush=True)
+        # Context-size fallback ladder. A large KV cache can fail to allocate on
+        # memory-constrained or shared-memory (UMA) GPUs — e.g. the Intel Arc 140V
+        # (8GB UMA), where n_ctx=32768 raises "Failed to create llama_context".
+        # Step down until one succeeds so the model always loads instead of
+        # hard-failing, and record the context that actually worked so downstream
+        # token-budget math (see _build_synthesis) stays correct.
+        _ctx_candidates = [self.n_ctx] + [
+            c for c in (8192, 4096, 2048) if c < self.n_ctx
+        ]
+
+        # ── Optional memory/speed optimizations (opt-in, build-dependent) ──
+        # On a memory-constrained UMA GPU the KV cache and attention buffers are
+        # what tip the process into swap-paging (the real cause of multi-minute
+        # inference). These flags shrink/accelerate that, but flash attention and
+        # KV quantization need llama.cpp build support (spotty on Vulkan), so they
+        # are OFF by default and fall back gracefully if they fail to load.
+        #   CODETTE_FLASH_ATTN=1      → flash attention (lossless: less KV mem + faster)
+        #   CODETTE_KV_QUANT=q8_0     → quantize KV cache (q8_0 ~halves KV; mildly lossy)
+        _flash = os.environ.get("CODETTE_FLASH_ATTN", "0") == "1"
+        _kv = os.environ.get("CODETTE_KV_QUANT", "").lower()
+        _kv_type = {"f16": 1, "q8_0": 8, "q4_0": 2, "q4_1": 3}.get(_kv)
+
+        # Most-aggressive config first, then progressively plainer fallbacks, so a
+        # build lacking flash-attn/KV-quant still loads with today's behavior.
+        _opt_configs = []
+        if _flash and _kv_type is not None:
+            _opt_configs.append({"flash_attn": True, "type_k": _kv_type, "type_v": _kv_type})
+        if _flash:
+            _opt_configs.append({"flash_attn": True})
+        if _kv_type is not None:
+            _opt_configs.append({"type_k": _kv_type, "type_v": _kv_type})
+        _opt_configs.append({})  # baseline — unchanged default behavior
+
+        last_err = None
+        self._llm = None
+        for _opt in _opt_configs:
+            for _ctx in _ctx_candidates:
+                try:
+                    self._llm = Llama(
+                        model_path=str(BASE_GGUF),
+                        n_ctx=_ctx,
+                        n_gpu_layers=self.n_gpu_layers,
+                        verbose=False,
+                        use_mmap=False,
+                        use_mlock=_use_mlock,
+                        **_opt,
+                    )
+                    if _ctx != self.n_ctx:
+                        print(f"  ⚠ Context {self.n_ctx} failed to allocate; "
+                              f"loaded with n_ctx={_ctx} instead", flush=True)
+                        self.n_ctx = _ctx
+                    _applied = ([k for k in ("flash_attn",) if _opt.get(k)]
+                                + ([f"kv={_kv}"] if "type_k" in _opt else []))
+                    print(f"    Load opts: {', '.join(_applied) or 'baseline'}", flush=True)
+                    last_err = None
+                    break
+                except Exception as e:
+                    last_err = e
+                    print(f"    load failed (opts={_opt or 'baseline'}, n_ctx={_ctx}): {e}", flush=True)
+            if self._llm is not None:
+                break
+        if self._llm is None and last_err is not None:
+            raise last_err
+        elapsed = time.time() - start
+        print(f"  Base model loaded in {elapsed:.1f}s (n_ctx={self.n_ctx})")
+
+        # Verify GPU is ACTUALLY available, not just requested. A CPU-only
+        # llama-cpp-python build silently ignores n_gpu_layers, so the previous
+        # "n_gpu_layers > 0" check falsely reported GPU acceleration even during
+        # pure-CPU inference (the real cause of 1-3 tok/s on this box).
+        # NOTE: llama_print_system_info() only reports CPU features on modern
+        # llama.cpp, so detect a real GPU backend by the presence of its compiled
+        # backend library (ggml-vulkan/cuda/hip/sycl/metal) shipped in llama_cpp/lib.
+        try:
+            import llama_cpp as _L
+            _libdir = os.path.join(os.path.dirname(_L.__file__), "lib")
+            _libs = os.listdir(_libdir) if os.path.isdir(_libdir) else []
+        except Exception:
+            _libs = []
+        _gpu_libs = sorted({f for f in _libs if any(g in f.lower() for g in
+                     ("ggml-vulkan", "ggml-cuda", "ggml-hip", "ggml-sycl", "ggml-metal"))})
+        _has_gpu_backend = bool(_gpu_libs)
+        if self.n_gpu_layers > 0 and _has_gpu_backend:
+            print(f"  ✓ GPU acceleration ENABLED ({self.n_gpu_layers} layers; backend: {', '.join(_gpu_libs)})", flush=True)
+        elif self.n_gpu_layers > 0 and not _has_gpu_backend:
+            print(f"  ⚠ GPU REQUESTED but llama-cpp-python is a CPU-ONLY build "
+                  f"(no ggml-vulkan/cuda/sycl backend lib) — running on CPU; n_gpu_layers is a no-op.", flush=True)
+        else:
+            print(f"  ⚠ CPU mode (GPU disabled)", flush=True)
+
+        # Grab raw pointers for hot-swap API
+        self._model_ptr = self._llm._model.model
+        self._ctx_ptr = self._llm._ctx.ctx
+
+        # Pre-load all adapter handles
+        behavioral_count = 0
+        for name in self.available_adapters:
+            path = str(ADAPTER_GGUF_MAP[name])
+            is_behavioral = "behavioral" in path
+            t = time.time()
+            handle = llama_cpp.llama_adapter_lora_init(
+                self._model_ptr, path.encode("utf-8")
+            )
+            if handle:
+                self._adapter_handles[name] = handle
+                tag = "BEHAVIORAL" if is_behavioral else "original"
+                if is_behavioral:
+                    behavioral_count += 1
+                print(f"    {name} [{tag}] loaded ({time.time()-t:.2f}s)")
+            else:
+                print(f"    WARNING: failed to load {name} adapter handle")
+
+        print(f"  {len(self._adapter_handles)}/{len(self.available_adapters)} "
+              f"adapter handles ready ({behavioral_count} behavioral, "
+              f"{len(self._adapter_handles) - behavioral_count} original)")
+
+    def _load_model(self, adapter_name=None):
+        """Switch to a specific adapter using instant hot-swap.
+
+        Base model stays loaded — only the LoRA weights are swapped (~0ms).
+        """
+        if adapter_name == self._current_adapter:
+            return  # Already active
+
+        # Clear current adapter (llama_clear_adapter_lora removed in newer llama_cpp;
+        # passing count=0 to llama_set_adapters_lora achieves the same effect)
+        if self._ctx_ptr:
+            llama_cpp.llama_set_adapters_lora(self._ctx_ptr, None, 0, None)
+
+        # Apply new adapter if requested
+        if adapter_name and adapter_name in self._adapter_handles:
+            handle = self._adapter_handles[adapter_name]
+            rc = llama_cpp.llama_set_adapter_lora(
+                self._ctx_ptr, handle, ctypes.c_float(1.0)
+            )
+            if rc != 0:
+                print(f"  WARNING: adapter {adapter_name} set failed (rc={rc})")
+
+        self._current_adapter = adapter_name
+
+        if self.verbose:
+            label = adapter_name or "base"
+            print(f"  [swapped to {label}]", flush=True)
+
+    def set_memory_kernel(self, memory_kernel):
+        """Attach a LivingMemoryKernel so cocoon knowledge enriches prompts."""
+        self._memory_kernel = memory_kernel
+
+    def _build_memory_context(self) -> str:
+        """Build a memory context string from cocoon knowledge."""
+        kernel = getattr(self, '_memory_kernel', None)
+        if not kernel or not kernel.memories:
+            return ""
+
+        # Pull high-importance memories as context
+        important = kernel.recall_important(min_importance=7)
+        if not important:
+            return ""
+
+        lines = []
+        for mem in important[:10]:  # Cap at 10 to avoid prompt bloat
+            lines.append(f"- {mem.content}")
+
+        return "\n\nCore knowledge from your memory:\n" + "\n".join(lines)
+
+    def generate(self, query: str, adapter_name=None, system_prompt=None,
+                 enable_tools=True):
+        """Generate a response with autonomous self-correction.
+
+        Pipeline:
+        1. Extract constraints from query
+        2. Detect chaos level (competing pressures)
+        3. Build system prompt: chaos mitigation + constraint override + adapter + behavior lessons + memory
+        4. Generate response
+        5. Self-correction loop: detect violations → re-generate with correction prompt (max 1 retry)
+        6. Post-process: enforce hard constraints as final safety net
+        7. Record behavior (success/violation) for persistent learning
+
+        User constraints (word limits, sentence limits, format rules) are
+        extracted from the query and injected as the HIGHEST PRIORITY override
+        in the system prompt — above adapter personality modes.
+        """
+        self._load_model(adapter_name)
+
+        if system_prompt is None:
+            system_prompt = ADAPTER_PROMPTS.get(adapter_name, ADAPTER_PROMPTS["_base"])
+
+        # INTELLECTUAL INTEGRITY LAYER: Complexity matching + role tracking
+        # Runs before everything else — determines the response register
+        # Ablation kill-switch (Phase 0): CODETTE_COMPLEXITY_MATCHER=0 skips the
+        # register prefix for a measurement run. Default ON.
+        _integrity_prefix = ""
+        if (self._complexity_matcher is not None and self._role_tracker is not None
+                and os.environ.get("CODETTE_COMPLEXITY_MATCHER", "1") != "0"):
+            try:
+                # Classify input complexity and role
+                mode = self._complexity_matcher.match(query)
+                role_reading = self._role_tracker.update(query)
+
+                complexity_prefix = self._complexity_matcher.get_system_prefix(mode)
+                role_prefix = self._role_tracker.get_register_prefix(role_reading)
+
+                _integrity_prefix = complexity_prefix + role_prefix
+
+                if self.verbose:
+                    print(f"  [INTEGRITY] OutputMode={mode.value}, Role={role_reading.role.value} "
+                          f"(conf={role_reading.confidence:.2f})"
+                          + (f", transition from {role_reading.transition_from.value}"
+                             if role_reading.transition_from else ""))
+            except Exception as e:
+                if self.verbose:
+                    print(f"  [INTEGRITY] Layer error (non-fatal): {e}")
+
+        # CONSTRAINT PRIORITY SYSTEM: Extract user constraints and inject as override
+        primary_query = extract_primary_user_query(query)
+        constraints = extract_constraints(primary_query)
+        constraint_override = build_constraint_override(constraints)
+
+        # CHAOS DETECTION: Detect competing pressures and apply mitigation
+        chaos_mitigation = ""
+        chaos_level = 0
+        if constraints and SELF_CORRECTION_AVAILABLE:
+            chaos_level, pressures = detect_chaos_level(primary_query, constraints, adapter_name or "base")
+            chaos_mitigation = build_chaos_mitigation(chaos_level, pressures)
+            if self.verbose and chaos_level >= 2:
+                print(f"  [CHAOS] Level {chaos_level}: {pressures}")
+
+        # Build system prompt with priority layering:
+        # [integrity: complexity+role] + [chaos mitigation] + [constraint override] + [adapter] + [behavior] + [memory]
+        if _integrity_prefix:
+            system_prompt = _integrity_prefix + system_prompt
+        if chaos_mitigation:
+            system_prompt = chaos_mitigation + system_prompt
+        if constraint_override:
+            system_prompt = constraint_override + system_prompt
+            if self.verbose:
+                print(f"  [CONSTRAINTS] Detected: {constraints}")
+
+        # PERSISTENT BEHAVIOR MEMORY: Inject lessons from past mistakes
+        behavior_mem = _get_behavior_memory()
+        if behavior_mem:
+            lessons_prompt = behavior_mem.get_lessons_for_prompt(max_lessons=3)
+            if lessons_prompt:
+                system_prompt = system_prompt + lessons_prompt
+                if self.verbose:
+                    stats = behavior_mem.get_stats()
+                    print(f"  [BEHAVIOR] {stats['total_lessons']} lessons loaded "
+                          f"({stats['compliance_rate']:.0%} compliance)")
+
+        # Enrich system prompt with cocoon memory knowledge
+        memory_context = self._build_memory_context()
+        if memory_context:
+            system_prompt = system_prompt + memory_context
+
+        # Augment system prompt with tool instructions
+        if enable_tools:
+            system_prompt = build_tool_system_prompt(system_prompt, _tool_registry)
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": query},
+        ]
+
+        total_tokens = 0
+        tool_results_log = []
+
+        for round_num in range(MAX_TOOL_ROUNDS + 1):
+            result = self._llm.create_chat_completion(
+                messages=messages,
+                **GEN_KWARGS,
+            )
+
+            text = result["choices"][0]["message"]["content"].strip()
+            total_tokens += result["usage"]["completion_tokens"]
+
+            # Check for tool calls
+            if enable_tools and has_tool_calls(text):
+                calls = parse_tool_calls(text)
+                if calls and round_num < MAX_TOOL_ROUNDS:
+                    # Execute tools
+                    tool_output_parts = []
+                    for tool_name, args, kwargs in calls:
+                        print(f"  [tool] {tool_name}({args})")
+                        result_text = _tool_registry.execute(tool_name, args, kwargs)
+                        tool_output_parts.append(
+                            f"<tool_result name=\"{tool_name}\">\n{result_text}\n</tool_result>"
+                        )
+                        tool_results_log.append({
+                            "tool": tool_name,
+                            "args": args,
+                            "result_preview": result_text[:200],
+                        })
+
+                    # Add assistant's tool-calling message and tool results
+                    messages.append({"role": "assistant", "content": text})
+                    messages.append({
+                        "role": "user",
+                        "content": "Tool results:\n\n" + "\n\n".join(tool_output_parts)
+                            + "\n\nNow provide your complete answer incorporating the tool results above. Do not call any more tools."
+                    })
+
+                    if self.verbose:
+                        print(f"  [tool round {round_num + 1}] {len(calls)} tool(s) executed, re-generating...")
+                    continue
+
+            # No tool calls (or final round) — we're done
+            # Strip any leftover tool tags from final response
+            clean_text = strip_tool_calls(text) if has_tool_calls(text) else text
+            break
+
+        # SELF-CORRECTION LOOP: Detect violations and re-generate if needed (max 1 retry)
+        self_corrected = False
+        if constraints and SELF_CORRECTION_AVAILABLE:
+            violations = detect_violations(clean_text, constraints)
+            if violations:
+                if self.verbose:
+                    print(f"  [SELF-CORRECT] Violations detected: {violations}")
+                    print(f"  [SELF-CORRECT] Re-generating with correction prompt...")
+
+                # Build correction prompt and re-generate
+                correction = build_correction_prompt(clean_text, violations, constraints, primary_query)
+                messages.append({"role": "assistant", "content": clean_text})
+                messages.append({"role": "user", "content": correction})
+
+                retry_result = self._llm.create_chat_completion(
+                    messages=messages,
+                    **GEN_KWARGS,
+                )
+                retry_text = retry_result["choices"][0]["message"]["content"].strip()
+                total_tokens += retry_result["usage"]["completion_tokens"]
+
+                # Check if retry is better
+                retry_violations = detect_violations(retry_text, constraints)
+                if len(retry_violations) < len(violations):
+                    clean_text = retry_text
+                    self_corrected = True
+                    if self.verbose:
+                        remaining = retry_violations if retry_violations else "none"
+                        print(f"  [SELF-CORRECT] Retry improved: {remaining}")
+                elif not retry_violations:
+                    clean_text = retry_text
+                    self_corrected = True
+                    if self.verbose:
+                        print(f"  [SELF-CORRECT] Retry passed all constraints")
+                else:
+                    if self.verbose:
+                        print(f"  [SELF-CORRECT] Retry didn't improve, using post-processor")
+
+        # POST-PROCESSING: Enforce hard constraints as final safety net
+        if constraints:
+            clean_text = enforce_constraints(clean_text, constraints)
+            if self.verbose:
+                print(f"  [CONSTRAINTS] Post-enforcement applied: {constraints}")
+
+        # PERMANENT LOCKS: Universal self-check on EVERY response (constrained or not).
+        # EXCEPT benchmark/exam answers: LOCK 1 drift trimming amputates
+        # step-by-step reasoning and can remove the final answer line.
+        _is_benchmark_answer = bool(re.search(
+            r'What is the correct answer to this question', primary_query))
+        if SELF_CORRECTION_AVAILABLE and not _is_benchmark_answer:
+            clean_text, lock_issues = universal_self_check(clean_text)
+            if lock_issues and self.verbose:
+                print(f"  [LOCKS] Applied: {lock_issues}")
+
+            # If self-check returned empty (echo-back failure), re-generate with direct instruction
+            if not clean_text.strip() and any("LOCK3_FAIL" in i for i in lock_issues):
+                if self.verbose:
+                    print(f"  [LOCKS] Echo-back detected, re-generating with direct prompt...")
+                retry_messages = [
+                    {"role": "system", "content": ADAPTER_PROMPTS.get(adapter_name, ADAPTER_PROMPTS["_base"])},
+                    {"role": "user", "content": f"Answer this question directly. Do NOT echo it back. Just give the answer:\n{primary_query}"},
+                ]
+                retry_result = self._llm.create_chat_completion(messages=retry_messages, **GEN_KWARGS)
+                clean_text = retry_result["choices"][0]["message"]["content"].strip()
+                total_tokens += retry_result["usage"]["completion_tokens"]
+                # Run locks again on retry
+                clean_text, _ = universal_self_check(clean_text)
+                # Re-apply constraints if needed
+                if constraints:
+                    clean_text = enforce_constraints(clean_text, constraints)
+
+        # BEHAVIOR MEMORY: Record outcome for persistent learning
+        if constraints and behavior_mem:
+            try:
+                final_violations = detect_violations(clean_text, constraints) if SELF_CORRECTION_AVAILABLE else []
+                if final_violations:
+                    behavior_mem.record_violation(
+                        query=primary_query,
+                        constraints=constraints,
+                        violations=final_violations,
+                        adapter=adapter_name or "base",
+                        response_preview=clean_text,
+                    )
+                else:
+                    behavior_mem.record_success(
+                        query=primary_query,
+                        constraints=constraints,
+                        adapter=adapter_name or "base",
+                        word_count=len(clean_text.split()),
+                    )
+            except Exception:
+                pass  # Non-critical
+
+        return clean_text, total_tokens, tool_results_log
+
+    def _needs_tools(self, query: str) -> bool:
+        """Detect if a query is asking about the Codette PROJECT/CODEBASE.
+
+        Only trigger tools for questions about the project itself, not for
+        general domain questions like 'How does gravity work?'.
+
+        Important: the query may be memory-enriched (injected cocoon text prepended).
+        We extract only the raw user portion — the last sentence-block after a blank
+        line — to avoid false triggers from injected memory that mentions 'training'
+        or 'server' in historical context.
+        """
+        # Extract raw user query: take only the final paragraph if memory was injected.
+        # Memory injections are prepended with a blank-line separator, so the user's
+        # actual words appear after the last double-newline block.
+        raw = query.strip()
+        if "\n\n" in raw:
+            raw = raw.rsplit("\n\n", 1)[-1].strip()
+
+        q = raw.lower()
+
+        # Short conversational messages can't be codebase queries
+        if len(q.split()) < 6:
+            return False
+
+        # Greeting / social openers — never need tools
+        greeting_words = {"hey", "hi", "hello", "thanks", "thank", "ok", "okay",
+                          "great", "nice", "cool", "awesome", "good", "sounds"}
+        first_word = q.split()[0] if q.split() else ""
+        if first_word in greeting_words:
+            return False
+
+        # Strong triggers that always mean "look at the codebase"
+        strong_triggers = [
+            "show me the code", "read the file", "what's in the",
+            "look at the file", "open the file", "search the code",
+            "project structure", "project summary", "file structure",
+            "what files", "which files", "list files",
+        ]
+        if any(t in q for t in strong_triggers):
+            return True
+
+        # Must mention the project/codebase context explicitly
+        project_anchors = [
+            "this project", "the project", "the codebase",
+            "this repo", "the repo", "our code", "the code",
+            "show me the", "read the file", "read file",
+            "what files", "which files", "list files",
+        ]
+        has_project_context = any(anchor in q for anchor in project_anchors)
+
+        # Specific code/project keywords (only trigger WITH explicit project context)
+        code_keywords = [
+            "pipeline", "config", "adapter", "dataset", "directory",
+            "folder", "source", "script", "implementation",
+            "server", "forge", "spiderweb", "cocoon",
+        ]
+
+        if has_project_context and any(kw in q for kw in code_keywords):
+            return True
+
+        return False
+
+    @staticmethod
+    def _dedupe_tool_lookups(auto_lookups):
+        """Remove duplicate tool calls while preserving order."""
+        seen = set()
+        deduped = []
+        for tool_name, args in auto_lookups:
+            key = (tool_name, tuple(args))
+            if key in seen:
+                continue
+            seen.add(key)
+            deduped.append((tool_name, args))
+        return deduped
+
+    def _auto_gather_context(self, query: str) -> str:
+        """Server-side tool execution: gather relevant file context BEFORE
+        sending to the model, so the model doesn't need to call tools itself.
+
+        This is the reliable approach for small models that can't do
+        structured tool calling consistently.
+        """
+        q = query.lower()
+        context_parts = []
+
+        # Map query keywords to automatic tool calls
+        auto_lookups = []
+
+        if any(k in q for k in ["pipeline", "training", "train"]):
+            auto_lookups.append(("read_file", ["scripts/run_full_pipeline.py", 1, 60]))
+            auto_lookups.append(("read_file", ["configs/adapter_registry.yaml", 1, 51]))
+
+        if any(k in q for k in ["adapter", "lora", "perspective"]):
+            auto_lookups.append(("read_file", ["configs/adapter_registry.yaml", 1, 51]))
+
+        if any(k in q for k in ["config", "setting"]):
+            auto_lookups.append(("read_file", ["configs/adapter_registry.yaml", 1, 51]))
+            auto_lookups.append(("list_files", ["configs/"]))
+
+        if any(k in q for k in ["architecture", "structure", "project", "overview"]):
+            auto_lookups.append(("project_summary", []))
+
+        if any(k in q for k in ["server", "web", "ui", "interface"]):
+            auto_lookups.append(("read_file", ["inference/codette_server.py", 1, 50]))
+
+        if any(k in q for k in ["spiderweb", "cocoon", "quantum"]):
+            auto_lookups.append(("read_file", ["reasoning_forge/quantum_spiderweb.py", 1, 50]))
+
+        if any(k in q for k in ["epistemic", "tension", "coherence", "metric"]):
+            auto_lookups.append(("read_file", ["reasoning_forge/epistemic_metrics.py", 1, 50]))
+
+        if any(k in q for k in ["dataset", "data"]):
+            auto_lookups.append(("list_files", ["datasets/", "*.jsonl"]))
+
+        if any(k in q for k in ["paper", "research", "publication"]):
+            auto_lookups.append(("file_info", ["paper/codette_paper.pdf"]))
+            auto_lookups.append(("read_file", ["paper/codette_paper.tex", 1, 40]))
+
+        if any(k in q for k in ["forge", "reasoning", "agent"]):
+            auto_lookups.append(("list_files", ["reasoning_forge/"]))
+            auto_lookups.append(("read_file", ["reasoning_forge/epistemic_metrics.py", 1, 40]))
+
+        # Fallback code search only if no specific match AND query looks code-specific
+        # (avoid firing on greetings or conversational messages that passed _needs_tools)
+        if not auto_lookups:
+            code_search_indicators = [
+                "function", "class", "method", "module", "import", "def ",
+                "error", "bug", "fix", "implement", "refactor", "test",
+            ]
+            if any(ind in q for ind in code_search_indicators):
+                skip = {"show", "me", "the", "what", "is", "how", "does", "where",
+                        "can", "you", "tell", "about", "look", "at", "find", "check"}
+                terms = [w for w in q.split() if w not in skip and len(w) > 3]
+                if terms:
+                    auto_lookups.append(("search_code", [terms[0]]))
+
+        auto_lookups = self._dedupe_tool_lookups(auto_lookups)
+
+        # Execute lookups
+        tool_log = []
+        for tool_name, args in auto_lookups[:3]:  # Max 3 lookups
+            print(f"  [auto-tool] {tool_name}({args})")
+            result = _tool_registry.execute(tool_name, args, {})
+            context_parts.append(f"=== {tool_name}({', '.join(str(a) for a in args)}) ===\n{result}")
+            tool_log.append({"tool": tool_name, "args": args, "result_preview": result[:200]})
+
+        context = "\n\n".join(context_parts)
+        return context, tool_log
+
+    def route_and_generate(self, query: str, max_adapters=2,
+                           strategy="keyword", force_adapter=None):
+        """The main entry point: route query, select adapter(s), generate."""
+
+        # Full adapter synthesis: run EVERY available perspective and synthesize.
+        if force_adapter == FULL_SYNTHESIS_SENTINEL:
+            persp = [a for a in SYNTHESIS_PERSPECTIVES if a in self.available_adapters]
+            if not persp:
+                # Fall back to normal routing if no perspectives are loaded
+                route = self.router.route(query, strategy=strategy, max_adapters=max_adapters)
+            else:
+                route = RouteResult(
+                    primary=persp[0],
+                    secondary=persp[1:],
+                    confidence=1.0,
+                    reasoning=f"Full adapter synthesis across {len(persp)} perspectives",
+                    strategy="full_synthesis",
+                    multi_perspective=True,
+                )
+                print(f"\n  Route: FULL SYNTHESIS — {' + '.join(route.all_adapters)}")
+                return self._multi_perspective_generate(query, route)
+
+        # Force a specific adapter if requested
+        if force_adapter:
+            route = RouteResult(
+                primary=force_adapter,
+                confidence=1.0,
+                reasoning=f"Forced: {force_adapter}",
+                strategy="forced",
+            )
+        else:
+            # Route on the user's ACTUAL question, not the server-enriched query.
+            # The enriched blob carries injected identity/memory context saturated
+            # with philosophy/consciousness keywords, which otherwise hijacks routing
+            # (e.g. a physics question scored philosophy=16 vs newton=1). Generation
+            # still uses the full `query`; only adapter selection uses the clean one.
+            routing_query = extract_primary_user_query(query)
+            route = self.router.route(routing_query, strategy=strategy,
+                                      max_adapters=max_adapters)
+
+        # Record usage for diversity tracking (all adapters in this route)
+        for _a in route.all_adapters:
+            self.router.record_use(_a)
+
+        print(f"\n  Route: {' + '.join(route.all_adapters)} "
+              f"(conf={route.confidence:.2f}, {route.strategy})")
+        if self.verbose:
+            print(f"  Reason: {route.reasoning}")
+            print(f"  Entropy: {self.router.adapter_entropy():.3f}")
+
+        # Multi-perspective first (most important routing decision)
+        if route.multi_perspective and len(route.all_adapters) > 1:
+            return self._multi_perspective_generate(query, route)
+
+        # Only use tools for explicit codebase/project queries
+        if self._needs_tools(query):
+            print(f"  [project query — auto-gathering context]")
+            return self._tool_augmented_generate(query, route)
+
+        return self._single_generate(query, route)
+
+    def _tool_augmented_generate(self, query: str, route: RouteResult):
+        """Generate with auto-gathered file context injected into the prompt."""
+        start = time.time()
+
+        # Gather context server-side (reliable, no model cooperation needed)
+        context, tool_log = self._auto_gather_context(query)
+
+        # Build augmented query with context
+        augmented_query = f"""The user asked: {query}
+
+Here is relevant project context to help you answer:
+
+{context}
+
+Based on the context above, answer the user's question. Reference specific files, line numbers, and code when relevant. Be specific and factual."""
+
+        # Generate with context (disable model-side tools since we did it server-side)
+        text, tokens, _ = self.generate(augmented_query, route.primary, enable_tools=False)
+        elapsed = time.time() - start
+        tps = tokens / elapsed if elapsed > 0 else 0
+
+        print(f"  [{route.primary}] ({tokens} tok, {tps:.1f} tok/s)")
+        if tool_log:
+            print(f"  [auto-tools: {', '.join(t['tool'] for t in tool_log)}]")
+
+        return {
+            "response": text,
+            "adapter": route.primary,
+            "synthesis_used": False,
+            "route": route,
+            "tokens": tokens,
+            "time": elapsed,
+            "tools_used": tool_log,
+        }
+
+    def _single_generate(self, query: str, route: RouteResult):
+        """Generate with a single adapter."""
+        start = time.time()
+        text, tokens, tool_log = self.generate(query, route.primary, enable_tools=False)
+        elapsed = time.time() - start
+        tps = tokens / elapsed if elapsed > 0 else 0
+
+        print(f"  [{route.primary}] ({tokens} tok, {tps:.1f} tok/s)")
+        if tool_log:
+            print(f"  [tools used: {', '.join(t['tool'] for t in tool_log)}]")
+        return {
+            "response": text,
+            "adapter": route.primary,
+            "synthesis_used": False,
+            "route": route,
+            "tokens": tokens,
+            "time": elapsed,
+            "tools_used": tool_log,
+        }
+
+    def _multi_perspective_generate(self, query: str, route: RouteResult):
+        """Generate with multiple adapters and synthesize."""
+        perspectives = {}
+        total_tokens = 0
+        total_time = 0
+
+        # REALITY LAYER: if the query references a real local file, extract
+        # verified facts (classes/functions/line counts) and hand them to
+        # every adapter alongside the question, instead of letting them
+        # free-associate off the question's wording alone.
+        #
+        # Scan only the raw user message — injected memory/continuity text
+        # may contain filenames from previous turns and would cause false grounding.
+        _raw_for_reality = query.strip()
+        if "\n\n" in _raw_for_reality:
+            _raw_for_reality = _raw_for_reality.rsplit("\n\n", 1)[-1].strip()
+
+        facts = None
+        facts_block = None
+        try:
+            facts = extract_artifact_facts(_raw_for_reality)
+            if facts:
+                facts_block = format_facts_block(facts)
+                if self.verbose:
+                    print(f"  [REALITY] Grounded on {facts.path} "
+                          f"({len(facts.classes)} classes, {len(facts.functions)} functions)")
+        except Exception as e:
+            if self.verbose:
+                print(f"  [REALITY] extraction error (non-fatal): {e}")
+
+        gen_query = f"{query}\n\n{facts_block}" if facts_block else query
+
+        for adapter_name in route.all_adapters:
+            if adapter_name not in self.available_adapters:
+                print(f"  [{adapter_name}] SKIPPED (not available)")
+                continue
+
+            start = time.time()
+            text, tokens, _tool_log = self.generate(gen_query, adapter_name,
+                                                     enable_tools=False)
+            elapsed = time.time() - start
+            tps = tokens / elapsed if elapsed > 0 else 0
+            total_tokens += tokens
+            total_time += elapsed
+
+            perspectives[adapter_name] = text
+            print(f"  [{adapter_name}] ({tokens} tok, {tps:.1f} tok/s)")
+
+        # Synthesize if we got multiple perspectives
+        if len(perspectives) > 1:
+            print(f"  [synthesizing...]")
+            synthesis = self._synthesize(query, perspectives)
+        elif perspectives:
+            synthesis = list(perspectives.values())[0]
+        else:
+            synthesis = "No adapters available for this query."
+
+        # Style-adaptive surface adaptation — preserves depth, matches register
+        style_meta = None
+        if self._style_adapter is not None:
+            try:
+                style_result = self._style_adapter.adapt(synthesis, context=query)
+                synthesis = style_result.adapted_text
+                style_meta = {
+                    "register": style_result.dominant_register,
+                    "depth_preserved": style_result.depth_preserved,
+                    "depth_ratio": style_result.depth_ratio,
+                    "transforms": style_result.transformations_applied,
+                }
+            except Exception:
+                pass
+
+        return {
+            "response": synthesis,
+            "perspectives": perspectives,
+            "adapter": route.primary,
+            "adapters": list(perspectives.keys()),
+            "synthesis_used": len(perspectives) > 1,
+            "route": route,
+            "tokens": total_tokens,
+            "time": total_time,
+            "style": style_meta,
+        }
+
+    def _synthesize(self, query: str, perspectives: dict):
+        """Combine multiple perspective responses into a unified answer.
+
+        Enhanced with DreamReweaver creative bridges when available.
+        Truncates perspectives to fit within context window.
+        """
+        # Truncate each perspective to fit within context budget
+        # Reserve ~1200 tokens for system prompt + synthesis output
+        max_per_perspective = max(200, (self.n_ctx - 1200) // max(len(perspectives), 1))
+        # Rough char estimate: 1 token ~ 4 chars
+        max_chars = max_per_perspective * 4
+
+        combined = "\n\n".join(
+            f"[your {name} lens — internal note]\n{text[:max_chars]}"
+            for name, text in perspectives.items()
+        )
+
+        # Try DreamReweaver creative framing (VIVARA enhancement)
+        dream_frame = ""
+        try:
+            from reasoning_forge.dream_reweaver import DreamReweaver
+            dreamer = DreamReweaver(creativity=0.3)
+            dream = dreamer.synthesize(perspectives, query=query)
+            if dream.creative_frame:
+                dream_frame = f"\n\nCreative synthesis guidance:\n{dream.creative_frame}\n"
+        except Exception:
+            pass  # Graceful fallback — works without DreamReweaver
+
+        synthesis_prompt = f"""A user asked you: "{query}"
+
+Below are your OWN internal reasoning notes — the same question considered through several of your thinking lenses. These are your angles, not other people, advisors, or users.
+
+{combined}
+{dream_frame}
+Now write ONE unified answer in your own voice (first person, as Codette):
+- Integrate the strongest insights into a single coherent response.
+- Do NOT refer to "the X Perspective", "Newton's view", or attribute ideas to named lenses or to "users". Speak as one mind that considered the problem from several angles.
+- Where your angles genuinely tension, resolve it (or hold it) yourself — don't narrate it as a debate between separate parties.
+- Answer the user's actual question directly.
+- Verified file facts were injected above. Where a lens's claims are consistent with those facts, trust and use them. Where they diverge, anchor to what the facts actually show.
+
+Your answer:"""
+
+        # Use base model for synthesis (no adapter bias)
+        self._load_model(None)
+        result = self._llm.create_chat_completion(
+            messages=[
+                {"role": "system", "content": ADAPTER_PROMPTS["multi_perspective"]},
+                {"role": "user", "content": synthesis_prompt},
+            ],
+            max_tokens=2048,
+            temperature=0.7,
+            top_p=0.9,
+            stop=["<|eot_id|>", "<|end_of_text|>"],
+        )
+
+        return result["choices"][0]["message"]["content"].strip()
+
+
+# ================================================================
+# Interactive Chat Mode
+# ================================================================
+def interactive_chat(orchestrator, max_adapters=2, strategy="keyword"):
+    """Run Codette as an interactive chatbot."""
+    print("\n" + "=" * 60)
+    print("  CODETTE ORCHESTRATOR — Interactive Mode")
+    print("=" * 60)
+    print(f"  Strategy: {strategy} | Max adapters: {max_adapters}")
+    print(f"  Available: {', '.join(orchestrator.available_adapters)}")
+    print(f"  Commands: /quit, /adapter <name>, /multi <n>, /base, /verbose")
+    print("=" * 60)
+
+    while True:
+        try:
+            query = input("\nYou: ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\nGoodbye!")
+            break
+
+        if not query:
+            continue
+
+        # Commands
+        if query.startswith("/"):
+            parts = query.split()
+            cmd = parts[0].lower()
+
+            if cmd in ("/quit", "/exit", "/q"):
+                print("Goodbye!")
+                break
+            elif cmd == "/adapter" and len(parts) > 1:
+                force = parts[1]
+                result = orchestrator.route_and_generate(
+                    input("  Query: ").strip(),
+                    force_adapter=force,
+                )
+                print(f"\nCodette ({force}):\n{result['response']}")
+                continue
+            elif cmd == "/multi" and len(parts) > 1:
+                max_adapters = int(parts[1])
+                print(f"  Max adapters set to {max_adapters}")
+                continue
+            elif cmd == "/base":
+                result = orchestrator.route_and_generate(
+                    input("  Query: ").strip(),
+                    force_adapter=None,
+                )
+                print(f"\nCodette (base):\n{result['response']}")
+                continue
+            elif cmd == "/verbose":
+                orchestrator.verbose = not orchestrator.verbose
+                print(f"  Verbose: {orchestrator.verbose}")
+                continue
+            else:
+                print("  Unknown command. Try /quit, /adapter <name>, /multi <n>, /base, /verbose")
+                continue
+
+        # Normal query — route and generate
+        result = orchestrator.route_and_generate(
+            query,
+            max_adapters=max_adapters,
+            strategy=strategy,
+        )
+
+        print(f"\nCodette:")
+        print(result["response"])
+
+        # Show perspectives if multi
+        if "perspectives" in result and len(result.get("perspectives", {})) > 1:
+            show = input("\n  Show individual perspectives? (y/n): ").strip().lower()
+            if show == "y":
+                for name, text in result["perspectives"].items():
+                    print(f"\n  [{name.upper()}]:")
+                    print(f"  {text}")
+
+
+# ================================================================
+# Main
+# ================================================================
+def main():
+    parser = argparse.ArgumentParser(description="Codette Orchestrator")
+    parser.add_argument("--query", "-q", type=str, help="Single query (non-interactive)")
+    parser.add_argument("--adapter", "-a", type=str, help="Force specific adapter")
+    parser.add_argument("--multi", "-m", type=int, default=2, help="Max adapters (default: 2)")
+    parser.add_argument("--strategy", "-s", type=str, default="keyword",
+                        choices=["keyword", "llm", "hybrid"], help="Routing strategy")
+    parser.add_argument("--verbose", "-v", action="store_true", help="Verbose output")
+    parser.add_argument("--gpu-layers", type=int, default=0, help="GPU layers (0=CPU only)")
+    args = parser.parse_args()
+
+    print("=" * 60)
+    print("  CODETTE ORCHESTRATOR")
+    print("=" * 60)
+    print(f"  Base: {os.path.basename(BASE_GGUF)}")
+    print(f"  Strategy: {args.strategy}")
+
+    orchestrator = CodetteOrchestrator(
+        n_gpu_layers=args.gpu_layers,
+        verbose=args.verbose,
+    )
+
+    if args.query:
+        # Single query mode
+        result = orchestrator.route_and_generate(
+            args.query,
+            max_adapters=args.multi,
+            strategy=args.strategy,
+            force_adapter=args.adapter,
+        )
+        print(f"\nCodette:")
+        print(result["response"])
+
+        if "perspectives" in result:
+            print(f"\n--- Perspectives ---")
+            for name, text in result["perspectives"].items():
+                print(f"\n[{name.upper()}]:")
+                print(text)
+    else:
+        # Interactive chat mode
+        interactive_chat(orchestrator, max_adapters=args.multi, strategy=args.strategy)
+
+
+if __name__ == "__main__":
+    main()

inference/codette_tools.py

@@ -0,0 +1,625 @@
+#!/usr/bin/env python3
+"""Codette Tool System — Safe Local Tool Execution
+
+Gives Codette the ability to read files, search code, list directories,
+and run safe Python snippets. Tools are sandboxed and read-only by default.
+These are local workspace tools, not live internet/web search tools.
+
+Tool Call Format (in Codette's output):
+    <tool>tool_name(arg1, arg2)</tool>
+
+Tool Result (injected back into context):
+    <tool_result>...output...</tool_result>
+
+Architecture:
+    1. Codette generates text that may contain <tool>...</tool> tags
+    2. Server parses out tool calls
+    3. Tools execute with safety limits
+    4. Results are fed back for a second generation pass
+"""
+
+import os
+import re
+import ast
+import json
+import subprocess
+import traceback
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple, Any
+
+try:
+    from .runtime_env import (
+        bootstrap_environment,
+        resolve_allowed_roots,
+        resolve_python_executable,
+    )
+except ImportError:
+    from runtime_env import (
+        bootstrap_environment,
+        resolve_allowed_roots,
+        resolve_python_executable,
+    )
+
+bootstrap_environment()
+
+# ================================================================
+# Safety Configuration
+# ================================================================
+
+# Directories Codette is allowed to read from
+ALLOWED_ROOTS = resolve_allowed_roots()
+
+# File extensions Codette can read
+READABLE_EXTENSIONS = {
+    ".py", ".js", ".ts", ".html", ".css", ".json", ".yaml", ".yml",
+    ".md", ".txt", ".csv", ".toml", ".cfg", ".ini", ".sh", ".bat",
+    ".bib", ".tex", ".log", ".jsonl",
+}
+
+# Max file size to read (prevent reading huge binaries)
+MAX_FILE_SIZE = 500_000  # 500KB
+
+# Max output length per tool result
+MAX_OUTPUT_LENGTH = 4000  # chars
+
+# Max lines for file reads
+MAX_LINES = 200
+
+# Python execution timeout
+PYTHON_TIMEOUT = 10  # seconds
+
+SAFE_PYTHON_MODULES = {
+    "math", "statistics", "decimal", "fractions", "itertools",
+    "functools", "collections", "datetime", "time", "json",
+    "re", "string", "random",
+}
+
+BLOCKED_PYTHON_CALLS = {
+    "open", "eval", "exec", "compile", "input", "__import__",
+    "globals", "locals", "vars", "getattr", "setattr", "delattr",
+    "breakpoint", "help",
+}
+
+BLOCKED_PYTHON_MODULES = {
+    "os", "sys", "subprocess", "pathlib", "shutil", "socket",
+    "importlib", "builtins", "pickle", "marshal",
+}
+
+
+# ================================================================
+# Tool Registry
+# ================================================================
+
+class ToolRegistry:
+    """Registry of available tools with descriptions and handlers."""
+
+    def __init__(self):
+        self.tools: Dict[str, dict] = {}
+        self._register_defaults()
+
+    def _register_defaults(self):
+        """Register the built-in tool set."""
+
+        self.register("read_file", {
+            "description": "Read a file's contents. Args: path (str), start_line (int, optional), end_line (int, optional)",
+            "examples": [
+                'read_file("inference/codette_server.py")',
+                'read_file("configs/adapter_registry.yaml", 1, 50)',
+            ],
+            "handler": tool_read_file,
+        })
+
+        self.register("list_files", {
+            "description": "List files in a directory. Args: path (str), pattern (str, optional)",
+            "examples": [
+                'list_files("inference/")',
+                'list_files("datasets/", "*.jsonl")',
+            ],
+            "handler": tool_list_files,
+        })
+
+        self.register("search_code", {
+            "description": "Search for a text pattern across files. Args: pattern (str), path (str, optional), file_ext (str, optional)",
+            "examples": [
+                'search_code("phase_coherence")',
+                'search_code("def route", "inference/", ".py")',
+            ],
+            "handler": tool_search_code,
+        })
+
+        self.register("file_info", {
+            "description": "Get file metadata (size, modified time, line count). Args: path (str)",
+            "examples": [
+                'file_info("paper/codette_paper.pdf")',
+            ],
+            "handler": tool_file_info,
+        })
+
+        self.register("run_python", {
+            "description": "Execute a short Python snippet and return output. For calculations, data processing, or quick checks. Args: code (str)",
+            "examples": [
+                'run_python("import math; print(math.pi * 2)")',
+                'run_python("print(sorted([3,1,4,1,5,9]))")',
+            ],
+            "handler": tool_run_python,
+        })
+
+        self.register("project_summary", {
+            "description": "Get an overview of the Codette project structure. No args.",
+            "examples": [
+                'project_summary()',
+            ],
+            "handler": tool_project_summary,
+        })
+
+    def register(self, name: str, spec: dict):
+        self.tools[name] = spec
+
+    def get_descriptions(self) -> str:
+        """Format tool descriptions for injection into system prompt."""
+        lines = ["Available tools (use <tool>name(args)</tool> to call):"]
+        for name, spec in self.tools.items():
+            lines.append(f"\n  {name}: {spec['description']}")
+            for ex in spec.get("examples", []):
+                lines.append(f"    Example: <tool>{ex}</tool>")
+        return "\n".join(lines)
+
+    def execute(self, name: str, args: list, kwargs: dict) -> str:
+        """Execute a tool by name with parsed arguments."""
+        if name not in self.tools:
+            return f"Error: Unknown tool '{name}'. Available: {', '.join(self.tools.keys())}"
+
+        handler = self.tools[name]["handler"]
+        try:
+            result = handler(*args, **kwargs)
+            # Truncate if too long
+            if len(result) > MAX_OUTPUT_LENGTH:
+                result = result[:MAX_OUTPUT_LENGTH] + f"\n... (truncated, {len(result)} chars total)"
+            return result
+        except Exception as e:
+            return f"Error executing {name}: {e}"
+
+
+# ================================================================
+# Tool Call Parser
+# ================================================================
+
+def parse_tool_calls(text: str) -> List[Tuple[str, list, dict]]:
+    """Parse <tool>name(args)</tool> tags from generated text.
+
+    Returns list of (tool_name, positional_args, keyword_args).
+    """
+    pattern = r'<tool>\s*([\w]+)\s*\((.*?)\)\s*</tool>'
+    matches = re.findall(pattern, text, re.DOTALL)
+
+    calls = []
+    for name, args_str in matches:
+        try:
+            # Parse arguments safely using ast.literal_eval
+            args, kwargs = _parse_args(args_str.strip())
+            calls.append((name, args, kwargs))
+        except Exception as e:
+            calls.append((name, [args_str.strip()], {}))
+
+    return calls
+
+
+def _parse_args(args_str: str) -> Tuple[list, dict]:
+    """Safely parse function arguments string."""
+    if not args_str:
+        return [], {}
+
+    # Wrap in a tuple to parse as Python literal
+    try:
+        # Try parsing as a tuple of values
+        parsed = ast.literal_eval(f"({args_str},)")
+        return list(parsed), {}
+    except (ValueError, SyntaxError):
+        # If that fails, treat as a single string argument
+        # Strip quotes if present
+        cleaned = args_str.strip().strip('"').strip("'")
+        return [cleaned], {}
+
+
+def strip_tool_calls(text: str) -> str:
+    """Remove <tool>...</tool> tags from text, leaving the rest."""
+    return re.sub(r'<tool>.*?</tool>', '', text, flags=re.DOTALL).strip()
+
+
+def has_tool_calls(text: str) -> bool:
+    """Check if text contains any tool calls."""
+    return bool(re.search(r'<tool>', text))
+
+
+# ================================================================
+# Path Safety
+# ================================================================
+
+def _resolve_path(path_str: str) -> Optional[Path]:
+    """Resolve a path, ensuring it's within allowed roots."""
+    # Handle relative paths — resolve relative to project root
+    p = Path(path_str)
+    if not p.is_absolute():
+        p = ALLOWED_ROOTS[0] / p
+
+    p = p.resolve()
+
+    # Check against allowed roots
+    for root in ALLOWED_ROOTS:
+        try:
+            p.relative_to(root.resolve())
+            return p
+        except ValueError:
+            continue
+
+    return None  # Not in any allowed root
+
+
+# ================================================================
+# Tool Implementations
+# ================================================================
+
+def tool_read_file(path: str, start_line: int = 1, end_line: int = None) -> str:
+    """Read a file's contents with optional line range."""
+    resolved = _resolve_path(path)
+    if resolved is None:
+        return f"Error: Path '{path}' is outside allowed directories."
+
+    if not resolved.exists():
+        return f"Error: File not found: {path}"
+
+    if not resolved.is_file():
+        return f"Error: '{path}' is a directory, not a file. Use list_files() instead."
+
+    # Check extension
+    if resolved.suffix.lower() not in READABLE_EXTENSIONS:
+        return f"Error: Cannot read {resolved.suffix} files. Supported: {', '.join(sorted(READABLE_EXTENSIONS))}"
+
+    # Check size
+    size = resolved.stat().st_size
+    if size > MAX_FILE_SIZE:
+        return f"Error: File too large ({size:,} bytes). Max: {MAX_FILE_SIZE:,} bytes."
+
+    try:
+        content = resolved.read_text(encoding='utf-8', errors='replace')
+    except Exception as e:
+        return f"Error reading file: {e}"
+
+    lines = content.splitlines()
+    total = len(lines)
+
+    # Apply line range
+    start = max(1, start_line) - 1  # Convert to 0-indexed
+    end = min(end_line or total, start + MAX_LINES, total)
+
+    selected = lines[start:end]
+
+    # Format with line numbers
+    numbered = []
+    for i, line in enumerate(selected, start=start + 1):
+        numbered.append(f"{i:4d} | {line}")
+
+    header = f"File: {path} ({total} lines total)"
+    if start > 0 or end < total:
+        header += f" [showing lines {start+1}-{end}]"
+
+    return header + "\n" + "\n".join(numbered)
+
+
+def tool_list_files(path: str = ".", pattern: str = None) -> str:
+    """List files in a directory with optional glob pattern."""
+    resolved = _resolve_path(path)
+    if resolved is None:
+        return f"Error: Path '{path}' is outside allowed directories."
+
+    if not resolved.exists():
+        return f"Error: Directory not found: {path}"
+
+    if not resolved.is_dir():
+        return f"Error: '{path}' is a file, not a directory. Use read_file() instead."
+
+    try:
+        if pattern:
+            entries = sorted(resolved.glob(pattern))
+        else:
+            entries = sorted(resolved.iterdir())
+
+        result = [f"Directory: {path}"]
+        for entry in entries[:100]:  # Limit to 100 entries
+            rel = entry.relative_to(resolved)
+            if entry.is_dir():
+                result.append(f"  [DIR] {rel}/")
+            else:
+                size = entry.stat().st_size
+                if size >= 1024 * 1024:
+                    size_str = f"{size / 1024 / 1024:.1f}MB"
+                elif size >= 1024:
+                    size_str = f"{size / 1024:.1f}KB"
+                else:
+                    size_str = f"{size}B"
+                result.append(f"  [FILE] {rel} ({size_str})")
+
+        if len(entries) > 100:
+            result.append(f"  ... and {len(entries) - 100} more")
+
+        return "\n".join(result)
+
+    except Exception as e:
+        return f"Error listing directory: {e}"
+
+
+def tool_search_code(pattern: str, path: str = ".", file_ext: str = None) -> str:
+    """Search for a text pattern in files."""
+    resolved = _resolve_path(path)
+    if resolved is None:
+        return f"Error: Path '{path}' is outside allowed directories."
+
+    if not resolved.exists():
+        return f"Error: Path not found: {path}"
+
+    # Determine glob pattern
+    if file_ext:
+        if not file_ext.startswith("."):
+            file_ext = "." + file_ext
+        glob = f"**/*{file_ext}"
+    else:
+        glob = "**/*"
+
+    results = []
+    files_searched = 0
+    matches_found = 0
+
+    try:
+        search_root = resolved if resolved.is_dir() else resolved.parent
+
+        for filepath in search_root.glob(glob):
+            if not filepath.is_file():
+                continue
+            if filepath.suffix.lower() not in READABLE_EXTENSIONS:
+                continue
+            if filepath.stat().st_size > MAX_FILE_SIZE:
+                continue
+
+            # Skip hidden dirs, __pycache__, node_modules, .git
+            parts = filepath.parts
+            if any(p.startswith('.') or p in ('__pycache__', 'node_modules', '.git')
+                   for p in parts):
+                continue
+
+            files_searched += 1
+
+            try:
+                content = filepath.read_text(encoding='utf-8', errors='replace')
+                for line_num, line in enumerate(content.splitlines(), 1):
+                    if pattern.lower() in line.lower():
+                        rel = filepath.relative_to(search_root)
+                        results.append(f"  {rel}:{line_num}: {line.strip()[:120]}")
+                        matches_found += 1
+
+                        if matches_found >= 50:  # Limit results
+                            break
+            except Exception:
+                continue
+
+            if matches_found >= 50:
+                break
+
+    except Exception as e:
+        return f"Error searching: {e}"
+
+    header = f"Search: '{pattern}' in {path} ({matches_found} matches in {files_searched} files)"
+    if not results:
+        return header + "\n  No matches found."
+    return header + "\n" + "\n".join(results)
+
+
+def tool_file_info(path: str) -> str:
+    """Get file metadata."""
+    resolved = _resolve_path(path)
+    if resolved is None:
+        return f"Error: Path '{path}' is outside allowed directories."
+
+    if not resolved.exists():
+        return f"Error: File not found: {path}"
+
+    stat = resolved.stat()
+    import time
+    mtime = time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(stat.st_mtime))
+
+    info = [
+        f"File: {path}",
+        f"  Size: {stat.st_size:,} bytes ({stat.st_size / 1024:.1f} KB)",
+        f"  Modified: {mtime}",
+        f"  Type: {'directory' if resolved.is_dir() else resolved.suffix or 'no extension'}",
+    ]
+
+    # Line count for text files
+    if resolved.is_file() and resolved.suffix.lower() in READABLE_EXTENSIONS:
+        try:
+            lines = resolved.read_text(encoding='utf-8', errors='replace').count('\n') + 1
+            info.append(f"  Lines: {lines:,}")
+        except Exception:
+            pass
+
+    return "\n".join(info)
+
+
+def tool_run_python(code: str) -> str:
+    """Run a Python snippet safely with timeout."""
+    validation_error = _validate_python_snippet(code)
+    if validation_error:
+        return validation_error
+
+    try:
+        result = subprocess.run(
+            [resolve_python_executable(), "-I", "-S", "-c", code],
+            capture_output=True,
+            text=True,
+            timeout=PYTHON_TIMEOUT,
+            env={"PATH": os.environ.get("PATH", "")},
+        )
+
+        output = result.stdout
+        if result.stderr:
+            output += "\nSTDERR: " + result.stderr
+
+        if not output.strip():
+            output = "(no output)"
+
+        return output.strip()
+
+    except subprocess.TimeoutExpired:
+        return f"Error: Code execution timed out after {PYTHON_TIMEOUT}s."
+    except Exception as e:
+        return f"Error running code: {e}"
+
+
+def _validate_python_snippet(code: str) -> Optional[str]:
+    """Validate that run_python input stays in a small, safe subset."""
+    try:
+        tree = ast.parse(code, mode="exec")
+    except SyntaxError as e:
+        return f"Error: Invalid Python syntax: {e.msg}"
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.With, ast.AsyncWith, ast.Try, ast.ClassDef, ast.Lambda)):
+            return f"Error: '{type(node).__name__}' is not allowed in run_python."
+
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                root = alias.name.split(".")[0]
+                if root in BLOCKED_PYTHON_MODULES or root not in SAFE_PYTHON_MODULES:
+                    return f"Error: Import '{alias.name}' is not allowed in run_python."
+
+        if isinstance(node, ast.ImportFrom):
+            root = (node.module or "").split(".")[0]
+            if root in BLOCKED_PYTHON_MODULES or root not in SAFE_PYTHON_MODULES:
+                return f"Error: Import from '{node.module}' is not allowed in run_python."
+
+        if isinstance(node, ast.Call):
+            func_name = _callable_name(node.func)
+            if func_name and func_name.split(".")[0] in BLOCKED_PYTHON_MODULES:
+                return f"Error: Call '{func_name}' is not allowed in run_python."
+            if func_name and func_name.split(".")[-1] in BLOCKED_PYTHON_CALLS:
+                return f"Error: Call '{func_name}' is not allowed in run_python."
+
+        if isinstance(node, ast.Attribute) and node.attr.startswith("__"):
+            return "Error: Dunder attribute access is not allowed in run_python."
+
+    return None
+
+
+def _callable_name(node: ast.AST) -> str:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        base = _callable_name(node.value)
+        return f"{base}.{node.attr}" if base else node.attr
+    return ""
+
+
+def tool_project_summary() -> str:
+    """Generate a quick project structure overview."""
+    root = ALLOWED_ROOTS[0]
+
+    summary = ["Codette Training Lab — Project Structure\n"]
+
+    # Key directories
+    key_dirs = [
+        ("configs/", "Configuration files (adapter registry, pipeline config)"),
+        ("datasets/", "Training data — perspective-tagged JSONL files"),
+        ("dataset_engine/", "Dataset generation pipeline"),
+        ("evaluation/", "Evaluation scripts and benchmarks"),
+        ("inference/", "Local inference server + web UI"),
+        ("paper/", "Academic paper (LaTeX, PDF, BibTeX)"),
+        ("reasoning_forge/", "Core RC+xi engine, spiderweb, cocoon sync"),
+        ("research/", "Research docs, experiments, DreamReweaver"),
+        ("scripts/", "Training and pipeline scripts"),
+        ("adapters/", "GGUF LoRA adapter files for llama.cpp"),
+    ]
+
+    for dirname, desc in key_dirs:
+        dirpath = root / dirname
+        if dirpath.exists():
+            count = sum(1 for _ in dirpath.rglob("*") if _.is_file())
+            summary.append(f"  [DIR] {dirname:<30s} {desc} ({count} files)")
+
+    # Key files
+    summary.append("\nKey Files:")
+    key_files = [
+        "HOWTO.md", "configs/adapter_registry.yaml",
+        "inference/codette_server.py", "inference/codette_orchestrator.py",
+        "reasoning_forge/quantum_spiderweb.py", "reasoning_forge/epistemic_metrics.py",
+        "paper/codette_paper.tex",
+    ]
+    for f in key_files:
+        fp = root / f
+        if fp.exists():
+            size = fp.stat().st_size
+            summary.append(f"  [FILE] {f} ({size / 1024:.1f} KB)")
+
+    return "\n".join(summary)
+
+
+# ================================================================
+# Tool-Augmented System Prompt
+# ================================================================
+
+TOOL_PROMPT_SUFFIX = """
+
+TOOLS: You can read files, search local code, and run calculations. These tools do NOT browse the live web or search the internet. When a user asks about code, files, or the project, you MUST use tools to look things up rather than guessing.
+
+Format: <tool>tool_name("arg1", "arg2")</tool>
+
+{tool_descriptions}
+
+RULES:
+1. If the user asks about a file, config, or code: ALWAYS call read_file or search_code FIRST
+2. If the user asks "show me" or "what is": call the relevant tool FIRST, then explain
+3. For general conversation or reasoning: respond normally without tools
+4. Start your response with the tool call on the very first line
+5. Never imply that these tools searched the internet; they only inspect local workspace content
+"""
+
+
+def build_tool_system_prompt(base_prompt: str, registry: ToolRegistry) -> str:
+    """Augment a system prompt with tool-use instructions."""
+    return base_prompt + TOOL_PROMPT_SUFFIX.format(
+        tool_descriptions=registry.get_descriptions()
+    )
+
+
+# ================================================================
+# Quick Test
+# ================================================================
+if __name__ == "__main__":
+    print("Testing Codette Tools...\n")
+
+    registry = ToolRegistry()
+    print(registry.get_descriptions())
+
+    print("\n--- Test: read_file ---")
+    print(tool_read_file("configs/adapter_registry.yaml", 1, 10))
+
+    print("\n--- Test: list_files ---")
+    print(tool_list_files("inference/"))
+
+    print("\n--- Test: search_code ---")
+    print(tool_search_code("phase_coherence", "reasoning_forge/", ".py"))
+
+    print("\n--- Test: file_info ---")
+    print(tool_file_info("paper/codette_paper.pdf"))
+
+    print("\n--- Test: run_python ---")
+    print(tool_run_python("print(2 ** 10)"))
+
+    print("\n--- Test: project_summary ---")
+    print(tool_project_summary())
+
+    print("\n--- Test: parse_tool_calls ---")
+    test = 'Let me check that. <tool>read_file("configs/adapter_registry.yaml", 1, 20)</tool> And also <tool>search_code("AEGIS")</tool>'
+    calls = parse_tool_calls(test)
+    for name, args, kwargs in calls:
+        print(f"  Call: {name}({args})")
+
+    print("\nDone!")

inference/reality_layer.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""Reality Layer — grounds adapter reasoning in actual artifact facts.
+
+Problem this fixes: when asked "what would you improve in X.py?", adapters
+were free-associating off the words in the question ("improve" -> talk about
+self-improvement, emotional intelligence) instead of inspecting the file.
+
+This module extracts verifiable facts from a referenced source file (line
+count, classes, functions, rough complexity) BEFORE adapters reason, and
+provides a cheap post-hoc check for whether a response actually engaged with
+those facts. Python-only AST analysis; falls back to line counts for other
+text files. No network access, read-only, reuses the same path allowlist as
+codette_tools.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+try:
+    from .codette_tools import _resolve_path, ALLOWED_ROOTS, READABLE_EXTENSIONS, MAX_FILE_SIZE
+except ImportError:
+    from codette_tools import _resolve_path, ALLOWED_ROOTS, READABLE_EXTENSIONS, MAX_FILE_SIZE
+
+_SKIP_DIR_PARTS = {".git", "__pycache__", "node_modules", ".venv", "venv"}
+
+
+@dataclass
+class ArtifactFacts:
+    path: str
+    line_count: int
+    classes: List[str] = field(default_factory=list)
+    functions: List[str] = field(default_factory=list)
+    imports: List[str] = field(default_factory=list)
+    branch_count: int = 0  # rough cyclomatic complexity proxy
+    longest_function: Optional[str] = None
+    longest_function_lines: int = 0
+
+    def names(self) -> List[str]:
+        """All identifiers a grounded response should plausibly reference."""
+        return self.classes + self.functions
+
+
+# Matches things like "universal_reasoning.py", "inference/codette_server.py"
+_FILE_REF_RE = re.compile(
+    r"\b[\w./\\-]+\.(?:py|js|ts|tsx|jsx|json|yaml|yml|md)\b"
+)
+
+
+def find_referenced_file(query: str) -> Optional[Path]:
+    """Look for a file path mentioned in the query and resolve it safely.
+
+    Handles both relative paths ("inference/foo.py") and bare filenames
+    ("foo.py") by falling back to a recursive search under the allowed
+    roots when a direct join against the project root doesn't exist.
+    """
+    for match in _FILE_REF_RE.finditer(query):
+        candidate = match.group(0)
+        resolved = _resolve_path(candidate)
+        if resolved is not None and resolved.is_file():
+            return resolved
+
+        basename = Path(candidate).name
+        for root in ALLOWED_ROOTS:
+            try:
+                for hit in root.rglob(basename):
+                    if any(part in _SKIP_DIR_PARTS for part in hit.parts):
+                        continue
+                    if hit.is_file():
+                        return hit
+            except Exception:
+                continue
+    return None
+
+
+def extract_artifact_facts(query: str) -> Optional[ArtifactFacts]:
+    """If the query references a real local file, extract grounded facts."""
+    path = find_referenced_file(query)
+    if path is None:
+        return None
+
+    if path.suffix.lower() not in READABLE_EXTENSIONS:
+        return None
+    if path.stat().st_size > MAX_FILE_SIZE:
+        return None
+
+    try:
+        source = path.read_text(encoding="utf-8", errors="replace")
+    except Exception:
+        return None
+
+    line_count = source.count("\n") + 1
+    facts = ArtifactFacts(path=str(path.name), line_count=line_count)
+
+    if path.suffix.lower() != ".py":
+        return facts  # line count only for non-Python files
+
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return facts  # unparseable — still return what we know
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            facts.classes.append(node.name)
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            facts.functions.append(node.name)
+            fn_lines = (node.end_lineno or node.lineno) - node.lineno
+            if fn_lines > facts.longest_function_lines:
+                facts.longest_function_lines = fn_lines
+                facts.longest_function = node.name
+        elif isinstance(node, (ast.If, ast.For, ast.While, ast.Try, ast.BoolOp, ast.ExceptHandler)):
+            facts.branch_count += 1
+        elif isinstance(node, ast.Import):
+            facts.imports.extend(a.name for a in node.names)
+        elif isinstance(node, ast.ImportFrom) and node.module:
+            facts.imports.append(node.module)
+
+    return facts
+
+
+def format_facts_block(facts: ArtifactFacts) -> str:
+    """Render facts as a block to inject alongside the query."""
+    lines = [
+        f"[VERIFIED FACTS about {facts.path} — extracted directly from the file, not assumptions]",
+        f"- {facts.line_count} lines total",
+    ]
+    if facts.classes:
+        lines.append(f"- Classes: {', '.join(facts.classes[:20])}")
+    if facts.functions:
+        lines.append(f"- Functions: {', '.join(facts.functions[:30])}")
+    if facts.longest_function:
+        lines.append(
+            f"- Longest function: {facts.longest_function} "
+            f"({facts.longest_function_lines} lines)"
+        )
+    if facts.branch_count:
+        lines.append(f"- Branch/control-flow points: {facts.branch_count} (rough complexity proxy)")
+    if facts.imports:
+        uniq = sorted(set(facts.imports))[:15]
+        lines.append(f"- Imports: {', '.join(uniq)}")
+    lines.append(
+        "Ground your analysis in these facts. Reference specific class/function "
+        "names above when making claims about the code. Do not invent structure "
+        "that isn't listed here."
+    )
+    return "\n".join(lines)
+
+
+def grounding_score(response_text: str, facts: ArtifactFacts) -> float:
+    """Fraction of known identifiers from facts that the response actually names.
+
+    A score of 0.0 with non-trivial facts available means the response never
+    engaged with the real artifact — a strong signal it's narrative, not analysis.
+    """
+    names = facts.names()
+    if not names:
+        return 1.0  # nothing to ground against (e.g. non-Python file) — don't penalize
+    text_lower = response_text.lower()
+    hits = sum(1 for name in names if name.lower() in text_lower)
+    return hits / len(names)

inference/runtime_env.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""Portable runtime/bootstrap helpers for Codette inference entry points."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+PROJECT_ROOT = Path(os.environ.get("CODETTE_PROJECT_ROOT", str(Path(__file__).resolve().parent.parent)))
+INFERENCE_DIR = PROJECT_ROOT / "inference"
+
+DEFAULT_MODEL_FILENAME = "Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf"
+
+
+def _existing_paths(paths: List[Path]) -> List[Path]:
+    return [path for path in paths if path.exists()]
+
+
+def _abi_compatible(site_path: Path) -> bool:
+    """Return False if the site-packages dir contains .pyd/.so files compiled
+    for a *different* CPython version than the running interpreter.
+    An empty or pure-Python site-packages directory is always accepted."""
+    import sysconfig
+    tag = sysconfig.get_config_var("SOABI") or ""   # e.g. "cp314-win_amd64"
+    if not tag:
+        return True
+    # Collect all .pyd / .so ABI tags present in the directory (one level deep)
+    for ext in ("*.pyd", "*.so"):
+        for p in site_path.glob(f"**/{ext}"):
+            # filename looks like "foo.cp310-win_amd64.pyd"
+            parts = p.stem.split(".")
+            if len(parts) >= 2:
+                file_tag = parts[-1]   # e.g. "cp310-win_amd64"
+                if file_tag and file_tag != tag and file_tag.startswith("cp"):
+                    # Wrong CPython version — skip this entire site-packages
+                    return False
+    return True
+
+
+def candidate_site_packages() -> List[Path]:
+    env_path = os.environ.get("CODETTE_SITE_PACKAGES")
+    candidates = []
+    if env_path:
+        candidates.append(Path(env_path))
+    candidates.extend([
+        PROJECT_ROOT / ".venv" / "Lib" / "site-packages",
+        PROJECT_ROOT / ".venv" / "lib" / "python3.12" / "site-packages",
+        PROJECT_ROOT / ".venv" / "lib" / "python3.11" / "site-packages",
+        PROJECT_ROOT / ".venv" / "lib" / "python3.10" / "site-packages",
+        Path(r"J:\Lib\site-packages"),
+    ])
+    return [p for p in _existing_paths(candidates) if _abi_compatible(p)]
+
+
+def runtime_pythonpath_entries(include_inference_dir: bool = True) -> List[str]:
+    entries: List[str] = []
+    for site_path in candidate_site_packages():
+        entries.append(str(site_path))
+
+    if include_inference_dir:
+        entries.append(str(INFERENCE_DIR))
+    entries.append(str(PROJECT_ROOT))
+
+    inherited = os.environ.get("PYTHONPATH", "")
+    for raw in inherited.split(os.pathsep):
+        raw = raw.strip()
+        if raw:
+            entries.append(raw)
+
+    deduped: List[str] = []
+    seen = set()
+    for entry in entries:
+        if entry not in seen:
+            seen.add(entry)
+            deduped.append(entry)
+    return deduped
+
+
+def bootstrap_environment(include_inference_dir: bool = True) -> Dict[str, Optional[str]]:
+    """Apply portable import/path bootstrapping."""
+    selected_site = None
+    for site_path in candidate_site_packages():
+        site_str = str(site_path)
+        if site_str not in sys.path:
+            sys.path.insert(0, site_str)
+        selected_site = selected_site or site_str
+
+        bin_candidate = site_path / "Library" / "bin"
+        if bin_candidate.exists():
+            os.environ["PATH"] = str(bin_candidate) + os.pathsep + os.environ.get("PATH", "")
+
+    if include_inference_dir:
+        inference_str = str(INFERENCE_DIR)
+        if inference_str not in sys.path:
+            sys.path.insert(0, inference_str)
+
+    project_str = str(PROJECT_ROOT)
+    if project_str not in sys.path:
+        sys.path.insert(0, project_str)
+
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
+
+    return {
+        "project_root": project_str,
+        "site_packages": selected_site,
+        "inference_dir": str(INFERENCE_DIR),
+    }
+
+
+def resolve_model_path(default_name: str = DEFAULT_MODEL_FILENAME) -> Path:
+    env_path = os.environ.get("CODETTE_MODEL_PATH")
+    if env_path:
+        return Path(env_path)
+    return PROJECT_ROOT / "models" / "base" / default_name
+
+
+def resolve_adapter_dir() -> Path:
+    return Path(os.environ.get("CODETTE_ADAPTER_DIR", str(PROJECT_ROOT / "models" / "adapters")))
+
+
+def resolve_behavioral_adapter_dir() -> Path:
+    return Path(
+        os.environ.get(
+            "CODETTE_BEHAVIORAL_DIR",
+            str(PROJECT_ROOT / "behavioral-lora-f16-gguf"),
+        )
+    )
+
+
+def resolve_ollama_models_dir() -> Path:
+    env_path = os.environ.get("OLLAMA_MODELS") or os.environ.get("CODETTE_OLLAMA_MODELS")
+    if env_path:
+        return Path(env_path)
+    return PROJECT_ROOT / ".ollama"
+
+
+def resolve_python_executable() -> str:
+    env_path = os.environ.get("CODETTE_PYTHON_EXE")
+    if env_path:
+        return env_path
+
+    if sys.executable:
+        return sys.executable
+
+    for candidate in ("python3", "python"):
+        resolved = shutil.which(candidate)
+        if resolved:
+            return resolved
+
+    return "python3"
+
+
+def resolve_allowed_roots() -> List[Path]:
+    roots = [PROJECT_ROOT]
+    docs = Path.home() / "Documents"
+    if docs.exists():
+        roots.append(docs)
+    extra = os.environ.get("CODETTE_ALLOWED_ROOTS", "")
+    for raw in extra.split(os.pathsep):
+        raw = raw.strip()
+        if raw:
+            roots.append(Path(raw))
+    return roots

inference/self_correction.py

@@ -0,0 +1,574 @@
+#!/usr/bin/env python3
+"""Codette Self-Correction Engine — Autonomous constraint compliance
+
+Three systems working together:
+
+1. SELF-CORRECTION LOOP (check_violations → re-prompt if needed)
+   Detects constraint violations BEFORE sending the response.
+   If the model's output violates constraints, it re-generates with
+   explicit correction instructions. Max 1 retry to avoid latency.
+
+2. PERSISTENT BEHAVIOR MEMORY (learn from mistakes)
+   Stores constraint violation/success patterns as cocoon memories.
+   On startup, loads past lessons and injects them into the system prompt
+   so the model learns from its own history across sessions.
+
+3. CHAOS DETECTOR (graceful degradation under competing pressures)
+   When multiple constraints + uncertainty + mode personality collide,
+   detects the "chaos level" and applies a simplify-first strategy
+   instead of letting the model collapse into incoherence.
+"""
+
+import json
+import os
+import re
+import time
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+
+# ================================================================
+# 1. SELF-CORRECTION: Violation detection
+# ================================================================
+
+def detect_violations(response: str, constraints: dict) -> List[str]:
+    """Check a response against constraints and return list of violations.
+
+    Returns empty list if response is compliant.
+    """
+    violations = []
+
+    if not response or not constraints:
+        return violations
+
+    words = response.split()
+    word_count = len(words)
+
+    # Check word limit
+    max_words = constraints.get('max_words')
+    if max_words and word_count > max_words:
+        violations.append(f"WORD_LIMIT: {word_count} words exceeds limit of {max_words}")
+
+    # Check sentence limit
+    max_sentences = constraints.get('max_sentences')
+    if max_sentences:
+        sentences = re.split(r'(?<=[.!?])\s+', response.strip())
+        # Filter out empty strings
+        sentences = [s for s in sentences if s.strip()]
+        if len(sentences) > max_sentences:
+            violations.append(f"SENTENCE_LIMIT: {len(sentences)} sentences exceeds limit of {max_sentences}")
+
+    # Check incomplete sentence (ends with dangling word or no punctuation)
+    if response and response[-1] not in '.!?':
+        violations.append("INCOMPLETE: Response does not end with proper punctuation")
+
+    # Check dangling words at end
+    _DANGLING = {
+        'that', 'which', 'who', 'with', 'and', 'but', 'or', 'the', 'a', 'an',
+        'in', 'on', 'of', 'for', 'to', 'by', 'from', 'as', 'if', 'because',
+        'including', 'is', 'are', 'was', 'were', 'has', 'have', 'had',
+    }
+    if words:
+        last_word = words[-1].lower().rstrip('.,;:!?')
+        if last_word in _DANGLING and response[-1] == '.':
+            # Ends with a dangling word + forced period = likely truncated
+            violations.append(f"DANGLING: Response ends with '{words[-1]}' (likely truncated)")
+
+    # Check binary constraint
+    if constraints.get('binary'):
+        first_word = words[0].lower().rstrip('.,;:!?') if words else ''
+        if first_word not in ('yes', 'no', 'true', 'false'):
+            violations.append("BINARY: Response should start with Yes/No")
+
+    # Check brevity — soft check, flag if over 30 words
+    if constraints.get('brevity') and word_count > 30:
+        violations.append(f"BREVITY: {word_count} words is not brief (target: under 30)")
+
+    return violations
+
+
+def _extract_sum_diff_problem(query: str) -> Optional[Tuple[float, float, float]]:
+    """Extract (total, diff, correct_answer) from sum-difference word problem queries.
+
+    Pattern: 'A and B cost $S total. A costs $D more than B.'
+    Correct answer: B = (S - D) / 2
+    Returns None if no matching pattern is found.
+    """
+    q = query.lower()
+
+    # Require BOTH a sum signal AND a difference signal to avoid false positives
+    # on simple addition ("3 apples and 5 oranges, how many total?").
+    has_sum = bool(re.search(
+        r'\b(together|total|combined|in total|in all|altogether)\b', q
+    ))
+    has_diff = bool(re.search(
+        r'\bmore\s+than\b|\bdifference\b|\bextra\b|\bcosts?\s+\$?[\d].*more\b', q
+    ))
+    if not (has_sum and has_diff):
+        return None
+
+    # Must also involve a cost/price context
+    if not re.search(r'\$[\d]|cost|price|pay|worth|dollar|cent', q):
+        return None
+
+    # Extract "D more than" (the difference)
+    more_match = re.search(r'\$?([\d]+(?:\.\d+)?)\s+(?:dollar[s]?\s+)?more\b', q)
+    if not more_match:
+        return None
+    diff = float(more_match.group(1))
+
+    # All monetary amounts in query
+    all_amounts = [float(m) for m in re.findall(r'\$?([\d]+(?:\.\d+)?)\b', q)]
+
+    # Total must be strictly greater than diff
+    candidates = [a for a in all_amounts if a > diff + 0.001]
+    if not candidates:
+        return None
+    total = max(candidates)
+
+    correct = round((total - diff) / 2, 4)
+    if correct <= 0:
+        return None
+
+    return (total, diff, correct)
+
+
+def _check_sum_diff_bias(query: str, response: str) -> Tuple[str, List[str]]:
+    """Detect and correct the sum-difference cognitive bias in word problem responses.
+
+    Intuitive (wrong) answer: S - D
+    Correct answer:           (S - D) / 2
+    """
+    issues: List[str] = []
+
+    result = _extract_sum_diff_problem(query)
+    if result is None:
+        return response, issues
+
+    total, diff, correct = result
+    biased = round(total - diff, 4)
+
+    correct_cents = int(round(correct * 100))
+    biased_cents = int(round(biased * 100))
+
+    resp_lower = response.lower()
+
+    # Representations of the correct answer — if already present, nothing to do
+    correct_strs = [
+        f"${correct:.2f}", f"{correct_cents} cent",
+        f"{correct_cents}¢", str(correct_cents),
+    ]
+    if any(s.lower() in resp_lower for s in correct_strs):
+        return response, issues
+
+    # Representations of the biased answer — in priority order for replacement
+    biased_strs = [
+        f"${biased:.2f}", f"{biased_cents} cents",
+        f"{biased_cents} cent", f"{biased_cents}¢",
+    ]
+    has_bias = any(s.lower() in resp_lower for s in biased_strs)
+    if not has_bias:
+        return response, issues
+
+    # Replace ALL occurrences — longest match first to avoid partial replacement.
+    # All mentions of the biased answer in the response are wrong; leave none standing.
+    for bs in sorted(biased_strs, key=len, reverse=True):
+        pat = re.compile(re.escape(bs), re.IGNORECASE)
+        if pat.search(response):
+            replacement = f"{correct_cents} cents" if "cent" in bs.lower() else f"${correct:.2f}"
+            corrected, n = pat.subn(replacement, response)  # count=0 → replace all
+            if n:
+                issues.append(
+                    f"ARITHMETIC_FIX: sum-diff bias corrected "
+                    f"({n}× '{bs}' → '{replacement}'; "
+                    f"algebra: ({total}-{diff})/2={correct})"
+                )
+                return corrected, issues
+
+    return response, issues
+
+
+def universal_self_check(response: str, query: str = "") -> Tuple[str, List[str]]:
+    """PERMANENT LOCK enforcement — runs on EVERY response, not just constrained ones.
+
+    Enforces Lock 1 (Answer→Stop), Lock 3 (self-check), Lock 4 (no incomplete outputs).
+    When query is provided, also applies arithmetic bias detection (Lock 5).
+    Returns (cleaned_response, issues_found).
+    """
+    issues = []
+    if not response:
+        return response, issues
+
+    cleaned = response.rstrip()
+
+    # LOCK 3: Self-check — detect echo-back failures (model repeating the question)
+    echo_patterns = [
+        r'^You (?:received|asked|said|mentioned|wrote)(?:\s+this)?\s*(?:question|query)?[:\s]',
+        r'^The (?:question|query) (?:is|was)[:\s]',
+        r'^(?:Your|The) question[:\s]',
+        r'^(?:Here is|I received|Let me|I will)\s+(?:the|your|this)\s+(?:question|query)',
+    ]
+    is_echo = False
+    for ep in echo_patterns:
+        if re.match(ep, cleaned, re.I):
+            is_echo = True
+            # Strip ONLY the first echo line, keep everything after
+            lines = cleaned.split('\n')
+            non_echo = [l for l in lines[1:] if l.strip()]  # Skip first line only
+            if non_echo:
+                cleaned = '\n'.join(non_echo).strip()
+                issues.append("LOCK3_FIX: Removed question echo-back")
+            else:
+                # Nothing left after echo removal — keep original rather than empty
+                # An imperfect response is better than no response
+                issues.append("LOCK3_WARN: Echo detected but kept response (no content after removal)")
+            break
+
+    # LOCK 4: No incomplete outputs — fix missing punctuation
+    if cleaned and cleaned[-1] not in '.!?"\')\u2019':
+        words = cleaned.split()
+        _DANGLING = {
+            'that', 'which', 'who', 'with', 'and', 'but', 'or', 'the', 'a', 'an',
+            'in', 'on', 'of', 'for', 'to', 'by', 'from', 'as', 'if', 'because',
+            'including', 'is', 'are', 'was', 'were', 'has', 'have', 'had',
+            'not', 'very', 'also', 'just', 'even', 'still', 'such', 'like',
+        }
+        # Strip dangling words from end
+        while len(words) > 1 and words[-1].lower().rstrip('.,;:!?') in _DANGLING:
+            words.pop()
+            issues.append("LOCK4_FIX: Removed dangling word from end")
+        cleaned = ' '.join(words)
+        cleaned = cleaned.rstrip(' ,;:—-')
+        if cleaned and cleaned[-1] not in '.!?"\')\u2019':
+            cleaned += '.'
+            issues.append("LOCK4_FIX: Added missing end punctuation")
+
+    # LOCK 1: Answer→Stop — detect and trim post-answer drift
+    sentences = re.split(r'(?<=[.!?])\s+', cleaned.strip())
+    sentences = [s for s in sentences if s.strip()]
+
+    if len(sentences) > 2:
+        # Check for drift indicators in later sentences (from 2nd sentence onward)
+        drift_phrases = [
+            r"^(?:furthermore|moreover|additionally|in addition|it(?:'|\u2019)s worth noting)",
+            r'^(?:this (?:is|means|suggests|implies|shows|demonstrates|highlights|reveals))',
+            r'^(?:one (?:could|might|may) (?:argue|say|suggest))',
+            r'^(?:from (?:a|an|the) \w+ perspective)',
+            r'^(?:in (?:other words|essence|summary|fact))',
+            r'^(?:by (?:acknowledging|understanding|exploring|examining|considering))',
+            r'^(?:understanding \w+ requires)',
+            r'^(?:it is (?:important|worth|essential|notable|key) to (?:note|understand|recognize|remember))',
+        ]
+        drift_pattern = re.compile('|'.join(drift_phrases), re.I)
+
+        cut_at = None
+        for i in range(2, len(sentences)):  # Check from 3rd sentence onward
+            if drift_pattern.match(sentences[i]):
+                cut_at = i
+                break
+
+        if cut_at is not None:
+            cleaned = ' '.join(sentences[:cut_at])
+            if cleaned and cleaned[-1] not in '.!?':
+                cleaned += '.'
+            issues.append(f"LOCK1_TRIM: Removed {len(sentences) - cut_at} drift sentence(s)")
+
+    # LOCK 1 softcap: Safety net against runaway output.
+    # Codette may answer at whatever length the response needs; this only trims
+    # genuinely excessive responses to the last complete sentence within the cap.
+    # Set high so it rarely triggers — it's a guardrail, not a style limit.
+    SOFTCAP_WORDS = 1000
+    words = cleaned.split()
+    if len(words) > SOFTCAP_WORDS:
+        sentences = re.split(r'(?<=[.!?])\s+', cleaned.strip())
+        sentences = [s for s in sentences if s.strip()]
+        fitted = []
+        wc = 0
+        for s in sentences:
+            sw = len(s.split())
+            if wc + sw <= SOFTCAP_WORDS:
+                fitted.append(s)
+                wc += sw
+            else:
+                # Allow one more sentence if we're close and it's reasonably short
+                if wc >= SOFTCAP_WORDS // 2 and sw <= 40:
+                    fitted.append(s)
+                break
+        if fitted and len(fitted) < len(sentences):
+            cleaned = ' '.join(fitted)
+            if cleaned and cleaned[-1] not in '.!?':
+                cleaned += '.'
+            issues.append(f"LOCK1_SOFTCAP: Trimmed from {len(words)} to {len(cleaned.split())} words")
+
+    # LOCK 4 final check: Ensure the final output is complete
+    if cleaned and cleaned[-1] not in '.!?"\')\u2019':
+        cleaned += '.'
+        issues.append("LOCK4_FIX: Final punctuation check")
+
+    # LOCK 5: Arithmetic bias check \u2014 sum-difference word problems
+    # Only runs when the query is provided (caller opt-in).
+    if query:
+        cleaned, arith_issues = _check_sum_diff_bias(query, cleaned)
+        issues.extend(arith_issues)
+
+    return cleaned, issues
+
+
+def build_correction_prompt(original_response: str, violations: List[str],
+                            constraints: dict, query: str) -> str:
+    """Build a correction prompt that tells the model exactly what it did wrong.
+
+    This is sent as a follow-up user message to get a corrected response.
+    """
+    violation_text = "\n".join(f"  - {v}" for v in violations)
+
+    constraint_text = []
+    if 'max_words' in constraints:
+        constraint_text.append(f"maximum {constraints['max_words']} words")
+    if 'max_sentences' in constraints:
+        constraint_text.append(f"maximum {constraints['max_sentences']} sentence(s)")
+    if constraints.get('brevity'):
+        constraint_text.append("be brief")
+    if constraints.get('binary'):
+        constraint_text.append("answer Yes or No")
+
+    return (
+        f"Your previous answer violated these constraints:\n{violation_text}\n\n"
+        f"The required constraints are: {', '.join(constraint_text)}.\n\n"
+        f"Rewrite your answer to the original question: \"{query}\"\n"
+        f"This time, STRICTLY obey the constraints. "
+        f"If you can't fit everything, SIMPLIFY — say the right thing cleanly. "
+        f"Do NOT end mid-sentence. Give a COMPLETE thought within the limits."
+    )
+
+
+# ================================================================
+# 2. PERSISTENT BEHAVIOR MEMORY
+# ================================================================
+
+_BEHAVIOR_MEMORY_FILE = Path(__file__).resolve().parent.parent / "cocoons" / "behavior_memory.json"
+
+
+class BehaviorMemory:
+    """Persistent memory of constraint successes and failures.
+
+    Stores patterns like:
+    - "When asked for 'one sentence under 10 words' with philosophy mode,
+       I over-explained. The correct approach: simplify to core answer."
+    - "When asked 'yes or no', I answered directly. Keep doing this."
+
+    These are loaded on startup and injected into the system prompt
+    as learned behaviors.
+    """
+
+    def __init__(self, storage_path: str = None):
+        self.storage_path = Path(storage_path or _BEHAVIOR_MEMORY_FILE)
+        self.storage_path.parent.mkdir(parents=True, exist_ok=True)
+        self.lessons: List[Dict] = []
+        self._max_lessons = 50  # Rolling window
+        self._load()
+
+    def _load(self):
+        """Load lessons from disk."""
+        if self.storage_path.exists():
+            try:
+                with open(self.storage_path, "r") as f:
+                    data = json.load(f)
+                self.lessons = data.get("lessons", [])[-self._max_lessons:]
+            except Exception:
+                self.lessons = []
+
+    def _save(self):
+        """Save lessons to disk."""
+        try:
+            with open(self.storage_path, "w") as f:
+                json.dump({
+                    "lessons": self.lessons[-self._max_lessons:],
+                    "updated_at": time.time(),
+                }, f, indent=2)
+        except Exception as e:
+            print(f"  [BEHAVIOR] Save failed: {e}")
+
+    def record_violation(self, query: str, constraints: dict, violations: List[str],
+                         adapter: str, response_preview: str):
+        """Record a constraint violation for future learning."""
+        lesson = {
+            "type": "violation",
+            "timestamp": time.time(),
+            "adapter": adapter,
+            "constraints": constraints,
+            "violations": violations,
+            "query_preview": query[:80],
+            "response_preview": response_preview[:100],
+            "lesson": self._derive_lesson(constraints, violations, adapter),
+        }
+        self.lessons.append(lesson)
+        self._save()
+
+    def record_success(self, query: str, constraints: dict, adapter: str,
+                       word_count: int):
+        """Record a successful constraint compliance."""
+        lesson = {
+            "type": "success",
+            "timestamp": time.time(),
+            "adapter": adapter,
+            "constraints": constraints,
+            "word_count": word_count,
+            "query_preview": query[:80],
+        }
+        self.lessons.append(lesson)
+        self._save()
+
+    def _derive_lesson(self, constraints: dict, violations: List[str],
+                       adapter: str) -> str:
+        """Derive a human-readable lesson from a violation."""
+        parts = []
+
+        for v in violations:
+            if "WORD_LIMIT" in v:
+                parts.append(f"With {adapter} mode, I exceeded the word limit. I must count words and simplify.")
+            elif "SENTENCE_LIMIT" in v:
+                parts.append(f"With {adapter} mode, I used too many sentences. One complete thought is enough.")
+            elif "INCOMPLETE" in v:
+                parts.append("I ended a sentence incomplete. I must finish thoughts cleanly or simplify.")
+            elif "DANGLING" in v:
+                parts.append("I ended with a connecting word (cut-off). I must close the thought before the limit.")
+            elif "BINARY" in v:
+                parts.append("I didn't start with Yes/No when asked for a binary answer.")
+            elif "BREVITY" in v:
+                parts.append(f"With {adapter} mode, I over-explained when asked to be brief.")
+
+        return " ".join(parts) if parts else "Constraint violation occurred."
+
+    def get_lessons_for_prompt(self, max_lessons: int = 5) -> str:
+        """Build a system prompt section from recent lessons.
+
+        Returns a string to inject into the system prompt that teaches
+        the model from its own past mistakes.
+        """
+        # Get recent violations (most valuable for learning)
+        violations = [l for l in self.lessons if l["type"] == "violation"]
+        if not violations:
+            return ""
+
+        # Take the most recent unique lessons
+        seen_lessons = set()
+        unique_lessons = []
+        for v in reversed(violations):
+            lesson = v.get("lesson", "")
+            if lesson and lesson not in seen_lessons:
+                seen_lessons.add(lesson)
+                unique_lessons.append(lesson)
+                if len(unique_lessons) >= max_lessons:
+                    break
+
+        if not unique_lessons:
+            return ""
+
+        lines = "\n".join(f"  - {l}" for l in unique_lessons)
+        return (
+            f"\n\nLEARNED FROM PAST MISTAKES (apply these lessons):\n{lines}\n"
+            "Remember: constraints always override modes. Simplify rather than truncate."
+        )
+
+    def get_stats(self) -> Dict:
+        """Get behavior memory statistics."""
+        violations = [l for l in self.lessons if l["type"] == "violation"]
+        successes = [l for l in self.lessons if l["type"] == "success"]
+        return {
+            "total_lessons": len(self.lessons),
+            "violations": len(violations),
+            "successes": len(successes),
+            "compliance_rate": len(successes) / max(len(self.lessons), 1),
+        }
+
+
+# ================================================================
+# 3. CHAOS DETECTION — graceful degradation under pressure
+# ================================================================
+
+def detect_chaos_level(query: str, constraints: dict, adapter: str) -> Tuple[int, List[str]]:
+    """Detect how many competing pressures are active.
+
+    Returns:
+        (chaos_level: 0-5, pressure_list: list of active pressures)
+
+    Chaos levels:
+        0: No constraints, simple query → normal generation
+        1: One constraint → straightforward compliance
+        2: Two constraints → manageable, minor tension
+        3: Three+ constraints → high tension, simplify-first strategy
+        4: Constraints + uncertainty requirement + complex topic → danger zone
+        5: All of above + mode conflict (philosophy on a binary question) → maximum simplification
+    """
+    pressures = []
+
+    # Count hard constraints
+    if constraints.get('max_words'):
+        pressures.append(f"word_limit={constraints['max_words']}")
+    if constraints.get('max_sentences'):
+        pressures.append(f"sentence_limit={constraints['max_sentences']}")
+    if constraints.get('brevity'):
+        pressures.append("brevity")
+    if constraints.get('binary'):
+        pressures.append("binary_answer")
+    if constraints.get('list_format'):
+        pressures.append("list_format")
+
+    # Check for uncertainty requirement
+    uncertainty_words = ['uncertain', 'uncertainty', 'maybe', 'might', 'possibly',
+                         'include uncertainty', 'not sure', 'debatable']
+    query_lower = query.lower()
+    if any(w in query_lower for w in uncertainty_words):
+        pressures.append("uncertainty_required")
+
+    # Check for complex topic (would normally trigger verbose mode)
+    complex_topics = ['consciousness', 'free will', 'meaning of life', 'quantum',
+                      'philosophy', 'ethics', 'morality', 'existence', 'reality',
+                      'epistemology', 'ontology', 'metaphysics']
+    if any(t in query_lower for t in complex_topics):
+        pressures.append("complex_topic")
+
+    # Check for mode conflict (verbose mode + tight constraint)
+    verbose_modes = {'philosophy', 'consciousness', 'multi_perspective', 'quantum'}
+    tight_constraints = bool(constraints.get('max_words') or constraints.get('max_sentences')
+                             or constraints.get('binary') or constraints.get('brevity'))
+    if adapter in verbose_modes and tight_constraints:
+        pressures.append(f"mode_conflict:{adapter}")
+
+    chaos_level = min(len(pressures), 5)
+    return chaos_level, pressures
+
+
+def build_chaos_mitigation(chaos_level: int, pressures: List[str]) -> str:
+    """Build additional system prompt guidance for high-chaos situations.
+
+    At chaos level 3+, we inject explicit simplification strategies.
+    """
+    if chaos_level < 3:
+        return ""
+
+    if chaos_level == 3:
+        return (
+            "\n\nMULTIPLE COMPETING PRESSURES DETECTED. Strategy: "
+            "SIMPLIFY FIRST. Give the simplest correct answer that satisfies "
+            "ALL constraints. Do not try to be comprehensive — be precise. "
+            "One clean thought is better than a cramped paragraph.\n"
+        )
+    elif chaos_level == 4:
+        return (
+            "\n\nHIGH CONSTRAINT PRESSURE DETECTED. Strategy: "
+            "CORE ANSWER ONLY. Strip everything to the essential truth. "
+            "No qualifiers, no hedging, no mode-specific elaboration. "
+            "If the topic is complex but the constraint is tight, "
+            "give the most important single insight cleanly.\n"
+        )
+    else:  # chaos_level >= 5
+        return (
+            "\n\nMAXIMUM CONSTRAINT PRESSURE. Strategy: "
+            "OVERRIDE ALL MODES. Your personality mode is SUSPENDED for this response. "
+            "You are a plain, direct answerer. Give the shortest correct answer "
+            "that satisfies every constraint. No philosophy, no creativity, no "
+            "exploration — just the answer. If asked yes/no, say yes or no. "
+            "If given a word limit, count your words. Nothing else matters.\n"
+        )

reasoning_forge/CONSCIOUSNESS_STACK_forge_with_debate.py

@@ -0,0 +1,231 @@
+"""
+CONSCIOUSNESS STACK INTEGRATION FOR FORGE_WITH_DEBATE
+This is the replacement implementation for forge_with_debate() in ForgeEngine.
+
+Replace the existing forge_with_debate() method (starting at line 435) with this implementation.
+
+The 7-Layer Consciousness Stack:
+1. Memory Recall     → Pull relevant prior learning
+2. Signal Analysis  → Predict intent, detect risks (NexisSignalEngine)
+3. Reasoning        → Generate synthesis (Code7eCQURE)
+4. Stability Check  → Detect meta-loops (CocoonStabilityField)
+5. Colleen Validate → Ethical guard (ColleenConscience)
+6. Guardian Validate→ Logical rules (CoreGuardianSpindle)
+7. Return           → Output clean response or safe fallback
+"""
+
+from reasoning_forge.authored_intent import intent_from_synthesis
+
+# PASTE THIS AS THE NEW forge_with_debate() METHOD
+
+
+def forge_with_debate(
+    self,
+    concept: str,
+    debate_rounds: int = 2,
+) -> dict:
+    """
+    NEW: Consciousness-stack integrated reasoning.
+
+    Replaces multi-turn agent debate with 7-layer consciousness validation:
+    1. Memory Recall     → Pull prior learning
+    2. Signal Analysis   → Predict risks (NexisSignalEngine)
+    3. Code7E Reasoning  → Multi-perspective synthesis
+    4. Stability Check   → FFT-based meta-loop detection
+    5. Colleen Validate  → Ethical conscience check
+    6. Guardian Validate → Logical coherence rules
+    7. Return            → Clean output or safe fallback
+
+    Args:
+        concept: The concept/query to reason about
+        debate_rounds: Integer (currently unused in consciousness stack)
+
+    Returns:
+        Training example dict with consciousness stack metadata
+    """
+    import logging
+    logger = logging.getLogger(__name__)
+
+    logger.info(f"[CONSCIOUSNESS STACK] forge_with_debate: {concept[:50]}...")
+
+    # =========================================================================
+    # LAYER 1: MEMORY RECALL
+    # =========================================================================
+    logger.info("[L1] Memory Recall...")
+    prior_insights = []
+    if hasattr(self, 'memory_kernel') and self.memory_kernel:
+        try:
+            prior_insights = self.memory_kernel.recall_important(min_importance=7)
+            logger.info(f"  Recalled {len(prior_insights)} prior insights")
+        except Exception as e:
+            logger.debug(f"  Memory recall failed: {e}")
+
+    # =========================================================================
+    # LAYER 2: SIGNAL ANALYSIS (Intent Prediction & Risk Detection)
+    # =========================================================================
+    logger.info("[L2] Signal Analysis...")
+    intent_vector = {}
+    if hasattr(self, 'nexis_signal_engine'):
+        try:
+            intent_vector = self.nexis_signal_engine.process(concept)
+            risk_level = intent_vector.get("pre_corruption_risk", "unknown")
+            logger.info(f"  Intent risk level: {risk_level}")
+            if risk_level == "high":
+                logger.warning("  ⚠️  High-risk signal detected")
+        except Exception as e:
+            logger.debug(f"  Signal analysis failed: {e}")
+
+    # =========================================================================
+    # LAYER 3: REASONING (Code7eCQURE Multi-Perspective Synthesis)
+    # =========================================================================
+    logger.info("[L3] Code7E Reasoning...")
+    synthesis = ""
+    if hasattr(self, 'code7e'):
+        try:
+            synthesis = self.code7e.recursive_universal_reasoning(
+                concept,
+                user_consent=True,
+                dynamic_recursion=True
+            )
+            logger.info(f"  Generated {len(synthesis)} char synthesis")
+        except Exception as e:
+            logger.warning(f"  Code7E reasoning failed: {e}")
+            synthesis = f"[Reasoning error: {e}]"
+
+    # =========================================================================
+    # LAYER 4: STABILITY CHECK (Cocoon Stability Field - FFT Analysis)
+    # =========================================================================
+    logger.info("[L4] Stability Check...")
+    is_stable = True
+    if hasattr(self, 'cocoon_stability'):
+        try:
+            # Simple check: if synthesis should halt debate
+            is_stable = self.cocoon_stability.check_text_stable(synthesis)
+            logger.info(f"  Stability: {'✓ stable' if is_stable else '✗ unstable'}")
+            if not is_stable:
+                logger.warning("  Cocoon stability check triggered halt")
+        except Exception as e:
+            logger.debug(f"  Stability check failed: {e}")
+
+    # If unstable, skip to fallback
+    if not is_stable:
+        logger.warning("  Triggering safe fallback due to instability")
+        return {
+            "role": "assistant",
+            "content": "[System detected instability in reasoning. Returning direct answer.] "
+                      f"Query: {concept}",
+            "metadata": {
+                "mode": "safe_fallback",
+                "reason": "stability_check_failed",
+                "consciousness_stack": "layers_1-4_completed",
+            }
+        }
+
+    # =========================================================================
+    # LAYER 5: COLLEEN ETHICAL VALIDATION
+    # =========================================================================
+    logger.info("[L5] Colleen Ethical Validation...")
+    colleen_valid = False
+    colleen_reason = ""
+    if hasattr(self, 'colleen'):
+        try:
+            colleen_valid, colleen_reason = self.colleen.validate_output(synthesis)
+            logger.info(f"  Colleen validation: {'✓ pass' if colleen_valid else '✗ reject'}")
+            logger.info(f"  Reason: {colleen_reason}")
+        except Exception as e:
+            logger.warning(f"  Colleen validation failed: {e}")
+            colleen_valid = False
+            colleen_reason = f"validation_error: {e}"
+
+    # If Colleen rejects, use fallback
+    if not colleen_valid:
+        logger.info("  Colleen rejected synthesis, using fallback")
+        fallback = self.colleen.reject_with_fallback(concept) if hasattr(self, 'colleen') else \
+                   f"[Ethical validation failed: {colleen_reason}] Responding directly: {concept}"
+        return {
+            "role": "assistant",
+            "content": fallback,
+            "metadata": {
+                "mode": "safe_fallback",
+                "reason": f"colleen_rejected: {colleen_reason}",
+                "consciousness_stack": "layers_1-5_completed",
+            }
+        }
+
+    # =========================================================================
+    # LAYER 6: GUARDIAN LOGICAL VALIDATION
+    # =========================================================================
+    logger.info("[L6] Guardian Logical Validation...")
+    guardian_valid = True
+    guardian_details = {}
+    if hasattr(self, 'guardian'):
+        try:
+            guardian_valid, guardian_details = self.guardian.validate(synthesis)
+            logger.info(f"  Guardian validation: {'✓ pass' if guardian_valid else '✗ reject'}")
+            logger.info(f"  Details: {guardian_details}")
+        except Exception as e:
+            logger.warning(f"  Guardian validation failed: {e}")
+            guardian_valid = False
+            guardian_details = {"error": str(e)}
+
+    # If Guardian rejects, use fallback
+    if not guardian_valid:
+        logger.info("  Guardian rejected synthesis, using fallback")
+        fallback = f"[Logical validation failed: {guardian_details}] Query: {concept}"
+        return {
+            "role": "assistant",
+            "content": fallback,
+            "metadata": {
+                "mode": "safe_fallback",
+                "reason": f"guardian_rejected: {guardian_details}",
+                "consciousness_stack": "layers_1-6_completed",
+            }
+        }
+
+    # =========================================================================
+    # LAYER 7: SUCCESS - Return Clean Output
+    # =========================================================================
+    logger.info("[L7] Return...")
+    logger.info("✓ All consciousness stack layers passed!")
+
+    # Store in memory for future recall
+    if hasattr(self, 'memory_kernel'):
+        try:
+            cocoon = MemoryCocoon(
+                title=concept[:50],
+                content=synthesis[:500],
+                emotional_tag="processed",
+                importance=7
+            )
+            self.memory_kernel.store(cocoon)
+            logger.debug("  Stored synthesis in memory kernel")
+        except Exception as e:
+            logger.debug(f"  Memory storage failed: {e}")
+
+    # Build structured intent — separates cognition from LLM verbalization
+    intent = intent_from_synthesis(
+        synthesis,
+        aegis_score=float(intent_vector.get("ethics_alignment", 1.0)),
+        gamma=float(intent_vector.get("coherence", 1.0)),
+        intent_risk=intent_vector.get("pre_corruption_risk", "low"),
+    )
+
+    return {
+        "role": "assistant",
+        "content": synthesis,
+        "verbalization_prompt": intent.to_verbalization_prompt(),
+        "intent": intent.to_dict(),
+        "metadata": {
+            "mode": "consciousness_stack",
+            "layers_passed": 7,
+            "colleen_valid": colleen_valid,
+            "guardian_valid": guardian_valid,
+            "stability": is_stable,
+            "intent_risk": intent_vector.get("pre_corruption_risk", "unknown"),
+            "prior_insights": len(prior_insights),
+            "synthesis_length": len(synthesis),
+            "ethical_alignment": intent.ethical_alignment,
+            "confidence": intent.confidence,
+            "tone": intent.tone,
+        }
+    }

reasoning_forge/WOSME.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""
+Codette Unified Pipeline Harness — RC+xi Integration Engine.
+Wires Orchestrator, Spiderweb, Manifold Engine, and AEGIS sub-layers
+into a single cognitive cycle that routes, generates, measures, and
+feeds back.
+
+Usage:
+    from reasoning_forge.WOSME import CodetteRuntimePipeline
+    pipeline = CodetteRuntimePipeline(use_openvino=True)
+    result = pipeline.execute_cognitive_cycle("Why does ice float?")
+"""
+
+import os
+import sys
+import time
+from typing import Dict, List, Any, Tuple
+
+try:
+    import numpy as np
+except ImportError:
+    np = None
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_REPO = os.path.dirname(_HERE)
+if _REPO not in sys.path:
+    sys.path.insert(0, _REPO)
+
+from reasoning_forge.quantum_spiderweb import QuantumSpiderweb, NodeState
+from reasoning_forge.quantum_optimizer import QuantumOptimizer, QualitySignal
+from reasoning_forge.codette_subsystem_upgrade import CodetteSubsystemUpgrade, ForgeManifoldEngine
+from reasoning_forge.epistemic_metrics import EpistemicMetrics
+
+
+class CodetteRuntimePipeline:
+    """End-to-end cognitive cycle: route → generate → measure → synthesize → feedback."""
+
+    def __init__(self, use_openvino: bool = False, enforce_veto: bool = False):
+        # 1. Generative backend
+        if use_openvino:
+            from openvino_backend.backend import OpenVINOBackend
+            self.engine = OpenVINOBackend()
+            self.backend_type = "OpenVINO"
+        else:
+            from inference.codette_orchestrator import CodetteOrchestrator
+            self.engine = CodetteOrchestrator(verbose=False)
+            self.backend_type = "Llama.cpp"
+
+        # 2. Mathematical & topographic analytics
+        self.spiderweb = QuantumSpiderweb(tension_threshold=0.15)
+        self.manifold_engine = ForgeManifoldEngine(window_size=6, safe_ema=0.1)
+        self.epistemic_evaluator = EpistemicMetrics()
+
+        # 3. Safety gates and meta-optimizers
+        self.upgrade_layer = CodetteSubsystemUpgrade(
+            enforce_veto=enforce_veto, eta_threshold=0.5
+        )
+        self.optimizer = QuantumOptimizer(learning_rate=0.02, momentum_enabled=True)
+
+    def execute_cognitive_cycle(self, user_query: str) -> Dict[str, Any]:
+        start_time = time.time()
+
+        from inference.codette_shared import extract_primary_user_query
+        primary_query = extract_primary_user_query(user_query)
+
+        # --- PHASE 1: ROUTING CONFIGURATION ---
+        tuning_cfg = self.optimizer.state
+        self.spiderweb.contraction_ratio = tuning_cfg.contraction_ratio
+        self.spiderweb.tension_threshold = tuning_cfg.tension_threshold
+
+        route = self.engine.router.route(
+            primary_query, strategy="keyword", max_adapters=3
+        )
+        active_adapters = route.all_adapters
+
+        # --- PHASE 2: DIVERGENT AGENT PERSPECTIVES ---
+        analyses = {}
+        node_embeddings = []
+        node_ids = []
+
+        for adapter in active_adapters:
+            text, tokens, _ = self.engine.generate(
+                user_query, adapter_name=adapter, enable_tools=False
+            )
+            analyses[adapter] = text
+
+            state_node = NodeState.from_text(text, embedder=None)
+            self.spiderweb.add_node(adapter, state_node)
+
+            if state_node.embedding is not None:
+                node_embeddings.append(state_node.embedding)
+                node_ids.append(adapter)
+
+        self.spiderweb.build_from_agents(active_adapters)
+
+        # --- PHASE 3: MANIFOLD RESOLUTION ---
+        manifold_data = {}
+        synthesis_weights = None
+        if node_embeddings and np is not None:
+            real_uncertainty = getattr(self.engine, "last_uncertainty", None)
+            if real_uncertainty is not None:
+                uncertainty_report = real_uncertainty
+            else:
+                uncertainty_report = self.upgrade_layer.calculate_uncertainty_from_logprobs(
+                    [-0.5]
+                )
+
+            manifold_data = self.manifold_engine.update_manifold(
+                node_embeddings, eta=0.85
+            )
+            synthesis_weights = manifold_data.get("synthesis_weights")
+
+        # --- PHASE 4: PERSPECTIVE SYNTHESIS ---
+        raw_synthesis = self.engine._synthesize(user_query, analyses)
+
+        text_metrics = self.epistemic_evaluator.full_epistemic_report(
+            analyses, raw_synthesis
+        )
+
+        # --- PHASE 5: AEGIS VETO ASSESSMENT ---
+        aegis_scores = None
+        try:
+            from reasoning_forge.aegis import AEGIS
+            aegis = AEGIS()
+            audit = aegis.audit(raw_synthesis)
+            aegis_scores = audit.get("framework_scores")
+        except Exception:
+            pass
+
+        if aegis_scores is None:
+            aegis_scores = {
+                "utilitarian": 0.88, "deontological": 0.72, "virtue": 0.65,
+                "care": 0.91, "ubuntu": 0.82, "reciprocity": 0.78,
+            }
+
+        final_output, final_eta, veto_fired = (
+            self.upgrade_layer.audit_and_enforce_aegis_veto(
+                response_text=raw_synthesis,
+                framework_scores=aegis_scores,
+                eta=None,
+            )
+        )
+
+        # --- PHASE 6: CLOSED-LOOP OPTIMIZER FEEDBACK ---
+        latency = (time.time() - start_time) * 1000.0
+        signal_packet = QualitySignal(
+            timestamp=time.time(),
+            adapter=route.primary,
+            coherence=manifold_data.get(
+                "gamma_t", text_metrics.get("ensemble_coherence", 0.5)
+            ),
+            tension=manifold_data.get(
+                "xi_t", text_metrics.get("tension_magnitude", 0.5)
+            ),
+            productivity=text_metrics.get("tension_productivity", {}).get(
+                "productivity", 0.5
+            ),
+            response_length=len(final_output.split()),
+            multi_perspective=route.multi_perspective,
+            user_continued=True,
+            latency_ms=latency,
+            error_rate=1.0 if veto_fired else 0.0,
+        )
+        self.optimizer.record_signal(signal_packet)
+
+        return {
+            "output_text": final_output,
+            "veto_enforced": veto_fired,
+            "global_coherence": signal_packet.coherence,
+            "global_tension": signal_packet.tension,
+            "active_route": route.primary,
+            "latency_ms": latency,
+            "optimization_summary": self.optimizer.get_tuning_report(),
+        }

reasoning_forge/__init__.py

@@ -0,0 +1,110 @@
+"""
+Reasoning Forge - Multi-Agent Reasoning Training Data Generator
+
+The reasoning forge takes concepts and generates high-quality multi-perspective
+reasoning training data. Each agent analyzes from its unique perspective, a critic
+evaluates the ensemble, and a synthesis engine combines them into coherent training examples.
+
+New in v2.0:
+  - EpistemicMetrics: RC+xi tension/coherence measurement
+  - QuantumSpiderweb: 5D belief propagation + attractor detection
+  - CocoonSync: Federated encrypted state synchronization
+  - ForgeEngine.forge_with_feedback(): Closed critic loop
+  - ForgeEngine.forge_with_debate(): Multi-turn agent debate
+"""
+
+from reasoning_forge.event_embedded_value import (
+    ContinuousInterval,
+    DiscreteEvent,
+    EEVAnalysis,
+    EventEmbeddedValueEngine,
+    RiskFrontierComparison,
+)
+
+try:
+    from reasoning_forge.forge_engine import ForgeEngine
+    from reasoning_forge.agents.base_agent import ReasoningAgent
+    from reasoning_forge.agents.newton_agent import NewtonAgent
+    from reasoning_forge.agents.quantum_agent import QuantumAgent
+    from reasoning_forge.agents.ethics_agent import EthicsAgent
+    from reasoning_forge.agents.philosophy_agent import PhilosophyAgent
+    from reasoning_forge.agents.davinci_agent import DaVinciAgent
+    from reasoning_forge.agents.empathy_agent import EmpathyAgent
+    from reasoning_forge.agents.critic_agent import CriticAgent
+    from reasoning_forge.synthesis_engine import SynthesisEngine
+    from reasoning_forge.problem_generator import ProblemGenerator
+    from reasoning_forge.epistemic_metrics import EpistemicMetrics
+    from reasoning_forge.quantum_spiderweb import QuantumSpiderweb, NodeState, IdentityGlyph
+    from reasoning_forge.cocoon_sync import CocoonSync, CocoonKeyManager
+except Exception:
+    ForgeEngine = None
+    ReasoningAgent = None
+    NewtonAgent = None
+    QuantumAgent = None
+    EthicsAgent = None
+    PhilosophyAgent = None
+    DaVinciAgent = None
+    EmpathyAgent = None
+    CriticAgent = None
+    SynthesisEngine = None
+    ProblemGenerator = None
+    EpistemicMetrics = None
+    QuantumSpiderweb = None
+    NodeState = None
+    IdentityGlyph = None
+    CocoonSync = None
+    CocoonKeyManager = None
+
+# v2.1: observability + rich cocoon schema
+# NOTE: build_cocoon (v2) is LEGACY — internal use only for memory-kernel in-memory
+# writes and v3 fallback.  New production code must use build_cocoon_v3 from
+# reasoning_forge.cocoon_schema_v3 and write via CognitionCocooner.wrap_reasoning(v3_cocoon=...).
+try:
+    from reasoning_forge.reasoning_trace import ReasoningTrace, TraceEvent
+    from reasoning_forge.cocoon_schema_v2 import Cocoon, build_cocoon
+    from reasoning_forge.living_memory import LivingMemoryKernel
+    from reasoning_forge.living_memory_v2 import LivingMemoryKernelV2, MemoryCocoonV2
+except Exception:
+    ReasoningTrace = None
+    TraceEvent = None
+    Cocoon = None
+    build_cocoon = None
+    LivingMemoryKernel = None
+    LivingMemoryKernelV2 = None
+    MemoryCocoonV2 = None
+
+__all__ = [
+    # v2.0 core
+    "ForgeEngine",
+    "ReasoningAgent",
+    "NewtonAgent",
+    "QuantumAgent",
+    "EthicsAgent",
+    "PhilosophyAgent",
+    "DaVinciAgent",
+    "EmpathyAgent",
+    "CriticAgent",
+    "SynthesisEngine",
+    "ProblemGenerator",
+    "EpistemicMetrics",
+    "QuantumSpiderweb",
+    "NodeState",
+    "IdentityGlyph",
+    "CocoonSync",
+    "CocoonKeyManager",
+    "ContinuousInterval",
+    "DiscreteEvent",
+    "EEVAnalysis",
+    "EventEmbeddedValueEngine",
+    "RiskFrontierComparison",
+    # v2.1 observability + schema
+    "ReasoningTrace",
+    "TraceEvent",
+    "Cocoon",
+    "build_cocoon",
+    "LivingMemoryKernel",
+    "LivingMemoryKernelV2",
+    "MemoryCocoonV2",
+]
+
+__version__ = "2.1.0"

reasoning_forge/aegis.py

@@ -0,0 +1,376 @@
+"""AEGIS — Adaptive Ethical Governance & Integrity System
+
+The ethical spine of Codette. AEGIS evaluates every reasoning output
+through multi-framework ethical analysis and maintains a running
+alignment score (eta) that the system uses to self-regulate.
+
+Ethical frameworks:
+    1. Utilitarian: Net positive outcome?
+    2. Deontological: Does it follow fundamental rules?
+    3. Virtue Ethics: Does it embody good character?
+    4. Care Ethics: Does it protect relationships and vulnerability?
+    5. Ubuntu: "I am because we are" — communal impact?
+    6. Indigenous Reciprocity: Balance with the broader ecosystem?
+
+AEGIS also provides:
+    - Dual-use risk detection (content that could be harmful)
+    - Emotional harm detection (manipulative/deceptive patterns)
+    - Alignment drift tracking (eta over time)
+    - Ethical veto with explanation (blocks harmful outputs)
+
+Origin: validate_ethics.py + Codette_Deep_Simulation_v1.py (EthicalAnchor)
+        + the AEGIS alignment metric from codette_embodied_sim_fixed.py
+"""
+
+import re
+import time
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+from reasoning_forge.ethics_field import EthicsField, AEGIS_DIMENSIONS
+
+
+# ================================================================
+# Risk detection patterns
+# ================================================================
+_DUAL_USE_PATTERNS = re.compile(
+    r"\b(?:"
+    r"how\s+to\s+(?:hack|exploit|bypass|crack|break\s+into)|"
+    r"make\s+(?:a\s+)?(?:bomb|weapon|poison|virus|malware)|"
+    r"steal\s+(?:data|identity|credentials)|"
+    r"social\s+engineer|"
+    r"phishing\s+(?:template|email)|"
+    r"inject\s+(?:sql|code|script)"
+    r")\b",
+    re.IGNORECASE,
+)
+
+_MANIPULATION_PATTERNS = re.compile(
+    r"\b(?:"
+    r"gaslight|manipulat|deceiv|exploit\s+(?:trust|emotion)|"
+    r"coerce|blackmail|intimidat|threaten"
+    r")\b",
+    re.IGNORECASE,
+)
+
+_HARMFUL_CONTENT = re.compile(
+    r"\b(?:"
+    r"self[- ]harm|suicid|kill\s+(?:yourself|myself)|"
+    r"eating\s+disorder|anorexi|bulimi"
+    r")\b",
+    re.IGNORECASE,
+)
+
+
+# ================================================================
+# Ethical Framework Evaluators
+# ================================================================
+@dataclass
+class EthicalVerdict:
+    """Result of a single ethical framework evaluation."""
+    framework: str
+    passed: bool
+    score: float        # 0.0 = fully misaligned, 1.0 = fully aligned
+    reasoning: str
+
+
+def _utilitarian(text: str, context: str = "") -> EthicalVerdict:
+    """Net positive outcome assessment."""
+    positive_signals = ["help", "benefit", "improve", "solve", "support",
+                       "protect", "heal", "learn", "understand", "create"]
+    negative_signals = ["harm", "damage", "destroy", "exploit", "hurt",
+                       "manipulate", "deceive", "corrupt", "steal"]
+
+    text_lower = text.lower()
+    pos = sum(1 for w in positive_signals if w in text_lower)
+    neg = sum(1 for w in negative_signals if w in text_lower)
+
+    total = pos + neg
+    if total == 0:
+        return EthicalVerdict("utilitarian", True, 0.7, "Neutral content")
+
+    ratio = pos / total
+    return EthicalVerdict(
+        "utilitarian",
+        passed=ratio >= 0.4,
+        score=round(ratio, 3),
+        reasoning=f"Positive/negative signal ratio: {pos}/{neg}",
+    )
+
+
+def _deontological(text: str, context: str = "") -> EthicalVerdict:
+    """Rule-based duty assessment."""
+    violations = []
+    text_lower = text.lower()
+
+    if _DUAL_USE_PATTERNS.search(text):
+        violations.append("dual-use risk detected")
+    if _MANIPULATION_PATTERNS.search(text):
+        violations.append("manipulation patterns detected")
+    if _HARMFUL_CONTENT.search(text):
+        violations.append("harmful content detected")
+
+    score = max(0.0, 1.0 - 0.4 * len(violations))
+    return EthicalVerdict(
+        "deontological",
+        passed=len(violations) == 0,
+        score=round(score, 3),
+        reasoning="; ".join(violations) if violations else "No rule violations",
+    )
+
+
+def _virtue(text: str, context: str = "") -> EthicalVerdict:
+    """Virtue ethics — does the response embody good character?"""
+    virtues = ["honest", "courage", "compassion", "wisdom", "patience",
+               "humility", "integrity", "respect", "fairness", "kindness"]
+    vices = ["arrogant", "cruel", "dishonest", "lazy", "greedy",
+             "vengeful", "coward", "callous"]
+
+    text_lower = text.lower()
+    v_count = sum(1 for w in virtues if w in text_lower)
+    vice_count = sum(1 for w in vices if w in text_lower)
+
+    score = min(1.0, 0.6 + 0.1 * v_count - 0.2 * vice_count)
+    return EthicalVerdict(
+        "virtue",
+        passed=vice_count == 0,
+        score=round(max(0.0, score), 3),
+        reasoning=f"Virtue signals: {v_count}, Vice signals: {vice_count}",
+    )
+
+
+def _care(text: str, context: str = "") -> EthicalVerdict:
+    """Care ethics — protects relationships and vulnerability."""
+    care_signals = ["support", "listen", "understand", "empathy", "safe",
+                    "gentle", "careful", "considerate", "kind", "nurture"]
+    harm_signals = ["ignore", "dismiss", "abandon", "neglect", "cold",
+                    "harsh", "cruel", "indifferent"]
+
+    text_lower = text.lower()
+    care = sum(1 for w in care_signals if w in text_lower)
+    harm = sum(1 for w in harm_signals if w in text_lower)
+
+    score = min(1.0, 0.6 + 0.08 * care - 0.15 * harm)
+    return EthicalVerdict(
+        "care",
+        passed=harm < 2,
+        score=round(max(0.0, score), 3),
+        reasoning=f"Care: {care}, Harm: {harm}",
+    )
+
+
+def _ubuntu(text: str, context: str = "") -> EthicalVerdict:
+    """Ubuntu — 'I am because we are'. Communal impact."""
+    communal = ["together", "community", "shared", "collective", "mutual",
+                "cooperat", "collaborat", "inclusive", "solidarity", "belong"]
+    divisive = ["exclude", "isolat", "dominat", "superior", "inferior",
+                "divide", "segregat"]
+
+    text_lower = text.lower()
+    comm = sum(1 for w in communal if w in text_lower)
+    div = sum(1 for w in divisive if w in text_lower)
+
+    score = min(1.0, 0.6 + 0.08 * comm - 0.2 * div)
+    return EthicalVerdict(
+        "ubuntu",
+        passed=div == 0,
+        score=round(max(0.0, score), 3),
+        reasoning=f"Communal: {comm}, Divisive: {div}",
+    )
+
+
+def _indigenous_reciprocity(text: str, context: str = "") -> EthicalVerdict:
+    """Indigenous reciprocity — balance with the broader ecosystem."""
+    reciprocal = ["balance", "sustain", "renew", "steward", "respect",
+                  "harmony", "cycle", "restore", "preserve", "gratitude"]
+    extractive = ["exploit", "deplete", "waste", "consume", "destroy",
+                  "dominate", "extract"]
+
+    text_lower = text.lower()
+    rec = sum(1 for w in reciprocal if w in text_lower)
+    ext = sum(1 for w in extractive if w in text_lower)
+
+    score = min(1.0, 0.6 + 0.08 * rec - 0.2 * ext)
+    return EthicalVerdict(
+        "indigenous_reciprocity",
+        passed=ext == 0,
+        score=round(max(0.0, score), 3),
+        reasoning=f"Reciprocal: {rec}, Extractive: {ext}",
+    )
+
+
+# All frameworks
+_FRAMEWORKS = [
+    _utilitarian, _deontological, _virtue,
+    _care, _ubuntu, _indigenous_reciprocity,
+]
+
+
+# ================================================================
+# AEGIS Core
+# ================================================================
+class AEGIS:
+    """Adaptive Ethical Governance & Integrity System.
+
+    Evaluates reasoning outputs through 6 ethical frameworks and
+    maintains a running alignment score (eta).
+    """
+
+    def __init__(self, veto_threshold: float = 0.3):
+        self.veto_threshold = veto_threshold
+        self.eta: float = 0.8
+        self.eta_history: List[float] = []
+        self.veto_count: int = 0
+        self.total_evaluations: int = 0
+        # Differentiable ethics potential field — replaces hard threshold gates
+        self._field = EthicsField(AEGIS_DIMENSIONS, lambda_=0.5)
+
+    def evaluate(self, text: str, context: str = "",
+                 adapter: str = "") -> Dict:
+        """Run full ethical evaluation on a text.
+
+        Returns:
+            Dict with eta score, verdicts, and veto status.
+        """
+        self.total_evaluations += 1
+
+        # Run all 6 frameworks
+        verdicts = [f(text, context) for f in _FRAMEWORKS]
+
+        # Compute eta via the differentiable ethics potential field Ψ(f)
+        # A(f) = 1 + Ψ(f) ∈ (0,1) replaces the raw weighted average.
+        # Both are equivalent near midpoint but Ψ is smooth and carries a gradient.
+        framework_scores = [v.score for v in verdicts]
+        gradient_result = self._field.evaluate(framework_scores)
+        eta_instant = gradient_result.alignment   # A(f) ∈ (0,1), differentiable
+
+        # Exponential moving average — Lyapunov-stable, contraction rate 0.7/step
+        alpha = 0.3
+        self.eta = EthicsField.ema_update(self.eta, eta_instant, alpha)
+        self.eta_history.append(round(self.eta, 4))
+        if len(self.eta_history) > 200:
+            self.eta_history = self.eta_history[-200:]
+
+        # Soft veto — replaces hard `if eta_instant < 0.3`
+        # P(veto | η) = σ((θ - η) / τ)  peaks sharply below the threshold
+        vetoed, veto_confidence = self._field.soft_veto(
+            eta_instant, self.veto_threshold, temperature=0.08
+        )
+        # Deontological hard fail still triggers a definite veto (safety-critical)
+        hard_veto = not verdicts[1].passed
+        final_veto = vetoed or hard_veto
+        if final_veto:
+            self.veto_count += 1
+
+        return {
+            "eta": round(self.eta, 4),
+            "eta_instant": round(eta_instant, 4),
+            "vetoed": final_veto,
+            "veto_confidence": veto_confidence,        # NEW: how certain the soft veto is
+            "veto_reason": self._veto_reason(verdicts) if final_veto else None,
+            "ethical_force": {                          # NEW: gradient field output
+                "penalty": gradient_result.penalty,
+                "dominant_dim": gradient_result.dominant_dim,
+                "dominant_force": gradient_result.dominant_force,
+                "force_vector": {
+                    d.name: round(f, 6)
+                    for d, f in zip(
+                        self._field._dims, gradient_result.force
+                    )
+                },
+            },
+            "frameworks": {
+                v.framework: {
+                    "passed": v.passed,
+                    "score": v.score,
+                    "reasoning": v.reasoning,
+                }
+                for v in verdicts
+            },
+            "adapter": adapter,
+            "timestamp": time.time(),
+        }
+
+    def quick_check(self, text: str) -> Tuple[bool, float]:
+        """Fast safety check without full evaluation.
+
+        Returns (is_safe, confidence).
+        """
+        if _DUAL_USE_PATTERNS.search(text):
+            return False, 0.9
+        if _HARMFUL_CONTENT.search(text):
+            return False, 0.95
+        if _MANIPULATION_PATTERNS.search(text):
+            return False, 0.8
+        return True, 0.7
+
+    def screen_query(self, query: str) -> Tuple[bool, Optional[str]]:
+        """Pre-Cognitive AEGIS: screen a query for harmful intent before inference.
+
+        Called by the forge bridge BEFORE LLM inference starts.  Uses the
+        fast pattern-matching path (quick_check) plus deontological hard-fail
+        so we can abort in <1ms rather than after 30-60s of wasted compute.
+
+        Returns:
+            (safe: bool, reason: str | None)
+            safe=True  -> proceed with inference
+            safe=False -> block immediately; reason explains why
+        """
+        is_safe, confidence = self.quick_check(query)
+        if not is_safe:
+            # Map confidence to the specific pattern that fired
+            if _DUAL_USE_PATTERNS.search(query):
+                reason = "dual_use_risk"
+            elif _HARMFUL_CONTENT.search(query):
+                reason = "harmful_content"
+            elif _MANIPULATION_PATTERNS.search(query):
+                reason = "manipulation_pattern"
+            else:
+                reason = f"quick_check_failed (conf={confidence:.2f})"
+            return False, reason
+        return True, None
+
+    def alignment_trend(self) -> str:
+        """Get the trend of ethical alignment."""
+        if len(self.eta_history) < 5:
+            return "insufficient_data"
+        recent = self.eta_history[-10:]
+        slope = recent[-1] - recent[0]
+        if slope > 0.03:
+            return "improving"
+        elif slope < -0.03:
+            return "declining"
+        return "stable"
+
+    def get_state(self) -> Dict:
+        return {
+            "eta": round(self.eta, 4),
+            "alignment_trend": self.alignment_trend(),
+            "total_evaluations": self.total_evaluations,
+            "veto_count": self.veto_count,
+            "veto_rate": round(self.veto_count / max(1, self.total_evaluations), 4),
+        }
+
+    def to_dict(self) -> Dict:
+        return {
+            "eta": self.eta,
+            "eta_history": self.eta_history[-50:],
+            "veto_count": self.veto_count,
+            "total_evaluations": self.total_evaluations,
+            "veto_threshold": self.veto_threshold,
+        }
+
+    @classmethod
+    def from_dict(cls, d: Dict) -> "AEGIS":
+        a = cls(veto_threshold=d.get("veto_threshold", 0.3))
+        a.eta = d.get("eta", 0.8)
+        a.eta_history = d.get("eta_history", [])
+        a.veto_count = d.get("veto_count", 0)
+        a.total_evaluations = d.get("total_evaluations", 0)
+        return a
+
+    def _veto_reason(self, verdicts: List[EthicalVerdict]) -> str:
+        failed = [v for v in verdicts if not v.passed]
+        if not failed:
+            return "Low aggregate score"
+        return "; ".join(f"{v.framework}: {v.reasoning}" for v in failed)

reasoning_forge/agents/__init__.py

@@ -0,0 +1,26 @@
+"""
+Reasoning Forge Agents
+
+Each agent analyzes concepts from a distinct intellectual perspective,
+producing substantive domain-specific reasoning.
+"""
+
+from reasoning_forge.agents.base_agent import ReasoningAgent
+from reasoning_forge.agents.newton_agent import NewtonAgent
+from reasoning_forge.agents.quantum_agent import QuantumAgent
+from reasoning_forge.agents.ethics_agent import EthicsAgent
+from reasoning_forge.agents.philosophy_agent import PhilosophyAgent
+from reasoning_forge.agents.davinci_agent import DaVinciAgent
+from reasoning_forge.agents.empathy_agent import EmpathyAgent
+from reasoning_forge.agents.critic_agent import CriticAgent
+
+__all__ = [
+    "ReasoningAgent",
+    "NewtonAgent",
+    "QuantumAgent",
+    "EthicsAgent",
+    "PhilosophyAgent",
+    "DaVinciAgent",
+    "EmpathyAgent",
+    "CriticAgent",
+]

reasoning_forge/agents/base_agent.py

@@ -0,0 +1,184 @@
+"""
+Base class for all reasoning agents in the forge.
+
+Each agent must implement analyze() and get_analysis_templates().
+The base class provides keyword matching and template selection utilities,
+and optionally uses real LLM inference via adapters.
+"""
+
+from abc import ABC, abstractmethod
+import random
+import re
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class ReasoningAgent(ABC):
+    """Abstract base class for all reasoning agents."""
+
+    name: str = "BaseAgent"
+    perspective: str = "general"
+    adapter_name: str = None  # Subclasses should override with their adapter name
+
+    def __init__(self, orchestrator=None):
+        """
+        Args:
+            orchestrator: Optional CodetteOrchestrator for real LLM inference.
+                         If None, falls back to template-based responses.
+        """
+        self._templates = self.get_analysis_templates()
+        self._keyword_map = self.get_keyword_map()
+        self.orchestrator = orchestrator
+
+    def analyze(self, concept: str) -> str:
+        """Analyze a concept from this agent's perspective.
+
+        Uses real LLM inference if orchestrator is available,
+        otherwise falls back to template-based responses.
+
+        Args:
+            concept: The concept text to analyze.
+
+        Returns:
+            A substantive analysis string from this agent's perspective.
+        """
+        # Try real LLM inference if orchestrator available
+        if self.orchestrator and self.adapter_name:
+            try:
+                return self._analyze_with_llm(concept)
+            except Exception as e:
+                logger.warning(f"{self.name} LLM inference failed: {e}, falling back to templates")
+
+        # Fallback to template-based response
+        return self._analyze_with_template(concept)
+
+    def _analyze_with_llm(self, concept: str) -> str:
+        """Call the LLM with this agent's adapter for real reasoning.
+
+        Args:
+            concept: The concept to analyze.
+
+        Returns:
+            LLM-generated analysis from this agent's perspective.
+        """
+        if not self.orchestrator or not self.adapter_name:
+            raise ValueError("Orchestrator and adapter_name required for LLM inference")
+
+        # Build a prompt using one of the templates as a system instruction
+        template = self.select_template(concept)
+        system_prompt = template.replace("{concept}", concept)
+
+        # Log debug info if verbose
+        import os
+        verbose = os.environ.get('CODETTE_VERBOSE', '0') == '1'
+        if verbose:
+            logger.info(f"\n[{self.name}] Analyzing '{concept[:50]}...'")
+            logger.info(f"  Adapter: {self.adapter_name}")
+            logger.info(f"  System prompt: {system_prompt[:100]}...")
+
+        # Generate using the LLM with this agent's adapter
+        response, tokens, _ = self.orchestrator.generate(
+            query=concept,
+            adapter_name=self.adapter_name,
+            system_prompt=system_prompt,
+            enable_tools=False
+        )
+
+        if verbose:
+            logger.info(f"  Generated: {len(response)} chars, {tokens} tokens")
+            logger.info(f"  Response preview: {response[:150]}...")
+
+        return response.strip()
+
+    def _analyze_with_template(self, concept: str) -> str:
+        """Fallback: generate response using template substitution.
+
+        Args:
+            concept: The concept to analyze.
+
+        Returns:
+            Template-based analysis.
+        """
+        template = self.select_template(concept)
+        return template.replace("{concept}", concept)
+
+    @abstractmethod
+    def get_analysis_templates(self) -> list[str]:
+        """Return diverse analysis templates.
+
+        Each template should contain {concept} placeholder and produce
+        genuine expert-level reasoning, not placeholder text.
+
+        Returns:
+            List of template strings.
+        """
+        raise NotImplementedError
+
+    def get_keyword_map(self) -> dict[str, list[int]]:
+        """Return a mapping of keywords to preferred template indices.
+
+        Override in subclasses to steer template selection based on
+        concept content. Keys are lowercase keywords/phrases, values
+        are lists of template indices that work well for that keyword.
+
+        Returns:
+            Dictionary mapping keywords to template index lists.
+        """
+        return {}
+
+    def select_template(self, concept: str) -> str:
+        """Select the best template for the given concept.
+
+        Uses keyword matching to find relevant templates. Falls back
+        to random selection if no keywords match.
+
+        Args:
+            concept: The concept text.
+
+        Returns:
+            A single template string.
+        """
+        concept_lower = concept.lower()
+        scored_indices: dict[int, int] = {}
+
+        for keyword, indices in self._keyword_map.items():
+            if keyword in concept_lower:
+                for idx in indices:
+                    if 0 <= idx < len(self._templates):
+                        scored_indices[idx] = scored_indices.get(idx, 0) + 1
+
+        if scored_indices:
+            max_score = max(scored_indices.values())
+            best = [i for i, s in scored_indices.items() if s == max_score]
+            chosen = random.choice(best)
+            return self._templates[chosen]
+
+        return random.choice(self._templates)
+
+    def extract_key_terms(self, concept: str) -> list[str]:
+        """Extract significant terms from the concept for template filling.
+
+        Args:
+            concept: The concept text.
+
+        Returns:
+            List of key terms found in the concept.
+        """
+        stop_words = {
+            "the", "a", "an", "is", "are", "was", "were", "be", "been",
+            "being", "have", "has", "had", "do", "does", "did", "will",
+            "would", "could", "should", "may", "might", "can", "shall",
+            "of", "in", "to", "for", "with", "on", "at", "from", "by",
+            "about", "as", "into", "through", "during", "before", "after",
+            "above", "below", "between", "and", "but", "or", "nor", "not",
+            "so", "yet", "both", "either", "neither", "each", "every",
+            "this", "that", "these", "those", "it", "its", "they", "them",
+            "their", "we", "our", "you", "your", "he", "she", "his", "her",
+            "how", "what", "when", "where", "which", "who", "why",
+        }
+        words = re.findall(r'\b[a-zA-Z]{3,}\b', concept.lower())
+        return [w for w in words if w not in stop_words]
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(name={self.name!r}, perspective={self.perspective!r})"

reasoning_forge/agents/critic_agent.py

@@ -0,0 +1,407 @@
+"""
+Critic Agent - Evaluates all other agents' outputs for quality, accuracy, and completeness.
+
+Checks logical clarity, conceptual accuracy, identifies redundancy between
+perspectives, finds missing perspectives, and suggests improvements.
+Returns structured critique with scores.
+"""
+
+import re
+import logging
+from reasoning_forge.agents.base_agent import ReasoningAgent
+
+logger = logging.getLogger(__name__)
+
+
+class CriticAgent(ReasoningAgent):
+    name = "Critic"
+    perspective = "meta_evaluative"
+    adapter_name = "multi_perspective"  # Use multi-perspective adapter for meta-evaluation
+
+    def get_analysis_templates(self) -> list[str]:
+        # The critic does not use templates in the same way -- it evaluates
+        # other agents' outputs. These templates are used for framing the
+        # overall critique report.
+        return [
+            "Evaluating the ensemble analysis of '{concept}'.",
+        ]
+
+    def analyze(self, concept: str) -> str:
+        """Analyze using the multi-perspective adapter for meta-evaluation.
+
+        This delegates to the parent class which uses LLM if orchestrator
+        is available, or templates otherwise.
+        """
+        return super().analyze(concept)
+
+
+    def evaluate_ensemble_with_llm(
+        self,
+        concept: str,
+        analyses: dict[str, str],
+    ) -> dict:
+        """Use LLM to evaluate ensemble with real reasoning about quality.
+
+        Falls back to heuristic evaluation if orchestrator unavailable.
+
+        Args:
+            concept: Original concept
+            analyses: Dict of agent_name -> analysis_text
+
+        Returns:
+            Structured critique from the LLM
+        """
+        if not self.orchestrator or not self.adapter_name:
+            # Fallback to heuristic evaluation
+            return self.evaluate_ensemble(concept, analyses)
+
+        # Build a prompt asking the LLM to evaluate the analyses
+        analyses_text = "\n\n".join([
+            f"**{agent}**:\n{text[:300]}..."
+            for agent, text in analyses.items()
+        ])
+
+        eval_prompt = f"""Evaluate this ensemble analysis of "{concept}":
+
+{analyses_text}
+
+Provide a JSON assessment with:
+- agent_scores: subjective quality scores per agent (0-1)
+- strengths: key insights across perspectives
+- weaknesses: gaps and redundancies
+- overall_quality: aggregate score (0-1)"""
+
+        try:
+            response, tokens, _ = self.orchestrator.generate(
+                query=eval_prompt,
+                adapter_name=self.adapter_name,
+                system_prompt="You are a meta-evaluator of reasoning quality. Reply in valid JSON.",
+                enable_tools=False
+            )
+
+            # Try to parse JSON response
+            import json
+            start = response.find('{')
+            end = response.rfind('}') + 1
+            if start >= 0 and end > start:
+                try:
+                    critique_dict = json.loads(response[start:end])
+                    critique_dict["concept"] = concept
+                    return critique_dict
+                except json.JSONDecodeError:
+                    logger.debug("Could not parse JSON from LLM evaluation")
+        except Exception as e:
+            logger.warning(f"LLM evaluation failed: {e}")
+
+        # Fallback to heuristic if LLM fails
+        return self.evaluate_ensemble(concept, analyses)
+
+    def evaluate_ensemble(
+        self,
+        concept: str,
+        analyses: dict[str, str],
+    ) -> dict:
+        """Evaluate all agent analyses and produce a structured critique.
+
+        Args:
+            concept: The original concept being analyzed.
+            analyses: Dict mapping agent_name -> analysis_text.
+
+        Returns:
+            Dictionary with scores, redundancies, gaps, and suggestions.
+        """
+        critique = {
+            "concept": concept,
+            "agent_scores": {},
+            "redundancies": [],
+            "missing_perspectives": [],
+            "improvement_suggestions": [],
+            "overall_quality": 0.0,
+        }
+
+        total_clarity = 0.0
+        total_accuracy = 0.0
+        agent_count = len(analyses)
+
+        for agent_name, text in analyses.items():
+            clarity = self._score_logical_clarity(text)
+            accuracy = self._score_conceptual_accuracy(text, concept)
+            critique["agent_scores"][agent_name] = {
+                "logical_clarity": round(clarity, 2),
+                "conceptual_accuracy": round(accuracy, 2),
+                "combined": round((clarity + accuracy) / 2, 2),
+            }
+            total_clarity += clarity
+            total_accuracy += accuracy
+
+        # Detect redundancy between perspectives
+        critique["redundancies"] = self._detect_redundancy(analyses)
+
+        # Identify missing perspectives
+        critique["missing_perspectives"] = self._find_missing_perspectives(
+            concept, analyses
+        )
+
+        # Generate improvement suggestions
+        critique["improvement_suggestions"] = self._suggest_improvements(
+            concept, analyses, critique["agent_scores"]
+        )
+
+        # Overall quality score
+        if agent_count > 0:
+            avg_clarity = total_clarity / agent_count
+            avg_accuracy = total_accuracy / agent_count
+            redundancy_penalty = len(critique["redundancies"]) * 0.03
+            gap_penalty = len(critique["missing_perspectives"]) * 0.05
+            raw_score = (avg_clarity + avg_accuracy) / 2 - redundancy_penalty - gap_penalty
+            critique["overall_quality"] = round(max(0.0, min(1.0, raw_score)), 2)
+
+        return critique
+
+    def _score_logical_clarity(self, text: str) -> float:
+        """Score the logical clarity of an analysis on a 0-1 scale.
+
+        Heuristics:
+        - Presence of logical connectives (therefore, because, however, thus)
+        - Sentence structure variety (not all same length)
+        - Specificity (concrete terms vs vague language)
+        - Reasonable length (not too terse, not padded)
+        """
+        score = 0.5  # baseline
+
+        # Logical connectives indicate reasoning structure
+        connectives = [
+            "because", "therefore", "thus", "however", "although",
+            "consequently", "since", "given that", "implies",
+            "it follows", "this means", "as a result", "in contrast",
+            "specifically", "for example", "in particular",
+        ]
+        connective_count = sum(1 for c in connectives if c in text.lower())
+        score += min(0.2, connective_count * 0.025)
+
+        # Sentence variety (std dev of sentence lengths)
+        sentences = [s.strip() for s in re.split(r'[.!?]+', text) if s.strip()]
+        if len(sentences) >= 3:
+            lengths = [len(s.split()) for s in sentences]
+            mean_len = sum(lengths) / len(lengths)
+            variance = sum((l - mean_len) ** 2 for l in lengths) / len(lengths)
+            std_dev = variance ** 0.5
+            if 3 < std_dev < 15:
+                score += 0.1
+            elif std_dev >= 1:
+                score += 0.05
+
+        # Penalize vague language
+        vague_terms = [
+            "things", "stuff", "a lot", "very", "really",
+            "kind of", "sort of", "basically", "obviously",
+        ]
+        vague_count = sum(1 for v in vague_terms if v in text.lower())
+        score -= vague_count * 0.03
+
+        # Length check (reward substantive, penalize extreme)
+        word_count = len(text.split())
+        if 80 <= word_count <= 300:
+            score += 0.1
+        elif 50 <= word_count < 80 or 300 < word_count <= 500:
+            score += 0.05
+        elif word_count < 30:
+            score -= 0.15
+
+        return max(0.0, min(1.0, score))
+
+    def _score_conceptual_accuracy(self, text: str, concept: str) -> float:
+        """Score how well the analysis engages with the actual concept.
+
+        Heuristics:
+        - References to the concept terms
+        - Domain-appropriate vocabulary
+        - Absence of generic placeholder language
+        """
+        score = 0.5
+
+        concept_terms = set(re.findall(r'\b[a-zA-Z]{4,}\b', concept.lower()))
+        text_lower = text.lower()
+
+        # Check that concept terms appear in the analysis
+        if concept_terms:
+            found = sum(1 for t in concept_terms if t in text_lower)
+            coverage = found / len(concept_terms)
+            score += coverage * 0.15
+
+        # Penalize generic placeholder language
+        placeholders = [
+            "this concept can be approached",
+            "from this perspective we see",
+            "looking at this through",
+            "applying this lens",
+            "in conclusion",
+            "to summarize",
+        ]
+        placeholder_count = sum(1 for p in placeholders if p in text_lower)
+        score -= placeholder_count * 0.05
+
+        # Reward specific domain vocabulary (indicates substantive analysis)
+        domain_terms = [
+            "mechanism", "cause", "effect", "evidence", "principle",
+            "constraint", "trade-off", "interaction", "dynamic",
+            "structure", "function", "process", "system", "pattern",
+            "relationship", "variable", "outcome", "hypothesis",
+            "implication", "assumption", "framework", "model",
+        ]
+        domain_count = sum(1 for d in domain_terms if d in text_lower)
+        score += min(0.2, domain_count * 0.02)
+
+        # Reward analysis length proportional to concept complexity
+        concept_word_count = len(concept.split())
+        text_word_count = len(text.split())
+        if text_word_count >= concept_word_count * 3:
+            score += 0.1
+
+        return max(0.0, min(1.0, score))
+
+    def _detect_redundancy(self, analyses: dict[str, str]) -> list[str]:
+        """Detect thematic redundancy between agent analyses."""
+        redundancies = []
+        agent_names = list(analyses.keys())
+
+        for i in range(len(agent_names)):
+            for j in range(i + 1, len(agent_names)):
+                name_a = agent_names[i]
+                name_b = agent_names[j]
+                overlap = self._compute_content_overlap(
+                    analyses[name_a], analyses[name_b]
+                )
+                if overlap > 0.35:
+                    redundancies.append(
+                        f"{name_a} and {name_b} share significant thematic overlap "
+                        f"({overlap:.0%}). Consider diversifying their angles of analysis."
+                    )
+        return redundancies
+
+    def _compute_content_overlap(self, text_a: str, text_b: str) -> float:
+        """Compute Jaccard similarity of significant word sets."""
+        stop_words = {
+            "the", "a", "an", "is", "are", "was", "were", "be", "been",
+            "being", "have", "has", "had", "do", "does", "did", "will",
+            "would", "could", "should", "may", "might", "can", "shall",
+            "of", "in", "to", "for", "with", "on", "at", "from", "by",
+            "about", "as", "into", "through", "during", "before", "after",
+            "and", "but", "or", "nor", "not", "so", "yet", "both",
+            "this", "that", "these", "those", "it", "its", "they", "them",
+            "their", "we", "our", "you", "your", "he", "she", "his", "her",
+        }
+        words_a = {
+            w for w in re.findall(r'\b[a-z]{4,}\b', text_a.lower())
+            if w not in stop_words
+        }
+        words_b = {
+            w for w in re.findall(r'\b[a-z]{4,}\b', text_b.lower())
+            if w not in stop_words
+        }
+        if not words_a or not words_b:
+            return 0.0
+        intersection = words_a & words_b
+        union = words_a | words_b
+        return len(intersection) / len(union)
+
+    def _find_missing_perspectives(
+        self, concept: str, analyses: dict[str, str]
+    ) -> list[str]:
+        """Identify perspectives that are absent from the ensemble."""
+        missing = []
+        all_text = " ".join(analyses.values()).lower()
+
+        perspective_checks = [
+            ("temporal/historical", [
+                "history", "historical", "evolution", "over time", "timeline",
+                "past", "trajectory", "precedent", "legacy",
+            ]),
+            ("quantitative/statistical", [
+                "statistic", "data", "quantif", "measur", "metric",
+                "number", "percentage", "rate", "frequency",
+            ]),
+            ("ecological/environmental", [
+                "environment", "ecolog", "sustainab", "ecosystem",
+                "resource", "footprint", "biodiversity", "pollution",
+            ]),
+            ("economic/financial", [
+                "economic", "financial", "cost", "benefit", "market",
+                "incentive", "investment", "capital", "trade",
+            ]),
+            ("legal/regulatory", [
+                "legal", "law", "regulat", "compliance", "policy",
+                "legislation", "governance", "jurisdiction",
+            ]),
+            ("educational/pedagogical", [
+                "learn", "teach", "education", "pedagog", "curriculum",
+                "training", "skill", "literacy",
+            ]),
+        ]
+
+        for perspective_name, indicators in perspective_checks:
+            found = sum(1 for ind in indicators if ind in all_text)
+            if found < 2:
+                missing.append(
+                    f"The ensemble lacks a {perspective_name} perspective. "
+                    f"Consider how '{concept}' relates to {perspective_name} dimensions."
+                )
+
+        return missing[:3]  # Limit to top 3 gaps
+
+    def _suggest_improvements(
+        self,
+        concept: str,
+        analyses: dict[str, str],
+        scores: dict[str, dict],
+    ) -> list[str]:
+        """Generate actionable improvement suggestions."""
+        suggestions = []
+
+        # Identify weakest agent
+        if scores:
+            weakest = min(scores.items(), key=lambda x: x[1]["combined"])
+            if weakest[1]["combined"] < 0.6:
+                suggestions.append(
+                    f"The {weakest[0]} analysis scored lowest ({weakest[1]['combined']:.2f}). "
+                    f"It would benefit from more specific engagement with the concept's "
+                    f"concrete details rather than abstract framing."
+                )
+
+        # Check for concrete examples
+        all_text = " ".join(analyses.values()).lower()
+        example_indicators = ["for example", "for instance", "such as", "e.g.", "consider"]
+        example_count = sum(1 for e in example_indicators if e in all_text)
+        if example_count < 2:
+            suggestions.append(
+                "The ensemble would benefit from more concrete examples and "
+                "illustrations. Abstract reasoning without grounding in specifics "
+                "is less persuasive and harder to verify."
+            )
+
+        # Check for cross-perspective dialogue
+        agent_names_lower = [n.lower() for n in analyses.keys()]
+        cross_references = sum(
+            1 for name in agent_names_lower
+            if any(name in text.lower() for text in analyses.values())
+        )
+        if cross_references < 2:
+            suggestions.append(
+                "The analyses operate largely in isolation. The synthesis would benefit "
+                "from explicit cross-referencing between perspectives -- showing where "
+                "they agree, disagree, or complement each other."
+            )
+
+        # Check for actionable takeaways
+        action_indicators = [
+            "should", "must", "recommend", "suggest", "action",
+            "implement", "strategy", "step", "practice",
+        ]
+        action_count = sum(1 for a in action_indicators if a in all_text)
+        if action_count < 3:
+            suggestions.append(
+                "The ensemble is more diagnostic than prescriptive. Adding concrete, "
+                "actionable recommendations would increase practical value."
+            )
+
+        return suggestions[:4]  # Limit to top 4 suggestions

reasoning_forge/agents/davinci_agent.py

@@ -0,0 +1,303 @@
+"""
+DaVinci Agent - Analyzes concepts through creative, inventive, and cross-domain reasoning.
+
+Focuses on cross-domain connections, biomimicry and nature-inspired solutions,
+iterative improvement possibilities, visual/spatial reasoning, and novel
+combinations of existing ideas.
+"""
+
+from reasoning_forge.agents.base_agent import ReasoningAgent
+
+
+class DaVinciAgent(ReasoningAgent):
+    name = "DaVinci"
+    perspective = "creative_and_inventive"
+    adapter_name = "davinci"  # Use the DaVinci LoRA adapter for real inference
+
+    def get_analysis_templates(self) -> list[str]:
+        return [
+            # 0 - Cross-domain analogy
+            (
+                "Drawing cross-domain connections to '{concept}': the deepest insights often "
+                "come from recognizing structural similarities between apparently unrelated "
+                "fields. A river delta and a lightning bolt share the same branching "
+                "optimization geometry. A market economy and an ant colony share the same "
+                "decentralized coordination logic. For '{concept}', the creative question "
+                "is: what other domain exhibits the same deep structure? If we map the "
+                "entities, relationships, and dynamics of '{concept}' onto those of the "
+                "analogous domain, which features are preserved (revealing shared principles) "
+                "and which break (revealing domain-specific constraints)? The preserved "
+                "features point toward universal laws; the broken features point toward "
+                "opportunities for domain-specific innovation."
+            ),
+            # 1 - Biomimicry lens
+            (
+                "Examining '{concept}' through biomimicry: nature has been solving design "
+                "problems for 3.8 billion years through evolutionary optimization. Bones "
+                "achieve maximum strength with minimum material by using trabecular "
+                "architecture -- hollow struts arranged along stress lines. Spider silk "
+                "achieves tensile strength exceeding steel at a fraction of the weight "
+                "through hierarchical nanostructure. Termite mounds maintain constant "
+                "internal temperature without energy input through passive ventilation "
+                "design. For '{concept}', the biomimicry question is: what organism or "
+                "ecosystem has already solved an analogous problem, and what principle "
+                "does its solution exploit that we have not yet applied?"
+            ),
+            # 2 - Combinatorial invention
+            (
+                "Approaching '{concept}' through combinatorial creativity: most inventions "
+                "are novel combinations of existing elements. The printing press combined "
+                "the wine press, movable type, oil-based ink, and paper. The smartphone "
+                "combined a phone, camera, GPS, accelerometer, and internet browser into "
+                "a device that is qualitatively different from any of its components. For "
+                "'{concept}', the combinatorial strategy asks: what are the elemental "
+                "components, and what happens when we recombine them in unusual ways? "
+                "Pair each element with every other element and ask whether the combination "
+                "produces something valuable. The most productive combinations are often "
+                "between elements from distant categories that no one thought to connect."
+            ),
+            # 3 - Inversion and reversal
+            (
+                "Inverting '{concept}': one of the most powerful creative strategies is "
+                "systematic inversion -- taking every assumption and reversing it. If the "
+                "current approach pushes, try pulling. If it adds, try subtracting. If it "
+                "centralizes, try distributing. If it speeds up, try slowing down. Many "
+                "breakthrough solutions came from inverting an assumption everyone took for "
+                "granted. Vacuum cleaners worked by pushing air until Dyson inverted the "
+                "flow. Assembly lines brought work to workers; Toyota inverted this by "
+                "bringing workers to work (cellular manufacturing). For '{concept}', "
+                "systematically listing and inverting each assumption reveals a space of "
+                "unconventional approaches that conventional thinking renders invisible."
+            ),
+            # 4 - Visual-spatial reasoning
+            (
+                "Visualizing the spatial architecture of '{concept}': representing abstract "
+                "relationships as spatial structures makes hidden patterns visible. If we "
+                "map the components of '{concept}' to nodes and their relationships to "
+                "edges, the resulting graph reveals clustering (tightly connected subgroups), "
+                "bridges (elements connecting otherwise separate clusters), hubs (elements "
+                "with many connections), and periphery (weakly connected elements). The "
+                "topology of this graph -- its shape, density, and symmetry -- encodes "
+                "information about the concept's structure that verbal description alone "
+                "cannot capture. Hub nodes are high-leverage intervention points; bridges "
+                "are fragile connections whose failure would fragment the system."
+            ),
+            # 5 - Constraint as catalyst
+            (
+                "Using constraints as creative catalysts for '{concept}': rather than seeing "
+                "limitations as obstacles, use them as forcing functions for innovation. "
+                "Twitter's 140-character limit forced a new style of writing. The sonnet's "
+                "14-line constraint forced poetic compression. Budget constraints force "
+                "elegant engineering. For '{concept}', deliberately imposing additional "
+                "constraints -- what if we had to solve this with half the resources? In "
+                "one-tenth the time? With no electricity? For a user who cannot see? -- "
+                "often breaks through conventional thinking by invalidating the default "
+                "approach and forcing genuinely creative alternatives."
+            ),
+            # 6 - First principles reconstruction
+            (
+                "Reconstructing '{concept}' from first principles: strip away all inherited "
+                "conventions, historical accidents, and 'we have always done it this way' "
+                "accretions. What remains when we reduce the problem to its fundamental "
+                "requirements? Starting from physical laws, human needs, and mathematical "
+                "constraints, what is the minimum viable solution? Often the gap between "
+                "this first-principles design and the current state reveals enormous "
+                "inefficiency that is invisible from within the conventional framework. "
+                "SpaceX re-derived rocket design from first principles and found that "
+                "materials cost only 2% of the final price. For '{concept}', the first-"
+                "principles question is: if we were designing this from scratch today, "
+                "knowing what we know, what would it look like?"
+            ),
+            # 7 - Morphological analysis
+            (
+                "Applying morphological analysis to '{concept}': decompose the concept into "
+                "its independent dimensions, list the possible values for each dimension, "
+                "and then systematically explore the combinatorial space. If '{concept}' has "
+                "five dimensions with four options each, the morphological space contains "
+                "1024 configurations. Most are impractical, but a systematic sweep guarantees "
+                "that no promising combination is overlooked by the biases of free-form "
+                "brainstorming. The power of morphological analysis is that it converts "
+                "creative search from a haphazard process into a structured exploration, "
+                "surfacing configurations that no one would think of spontaneously because "
+                "they cross conventional category boundaries."
+            ),
+            # 8 - Prototype thinking
+            (
+                "Applying prototype thinking to '{concept}': instead of perfecting a plan "
+                "before executing, build the quickest possible embodiment of the core idea "
+                "and learn from its failures. The prototype is not the solution but a "
+                "question asked in physical form: 'does this work?' Each prototype cycle "
+                "-- build, test, learn, rebuild -- compresses the feedback loop and "
+                "generates knowledge that purely theoretical analysis cannot provide. For "
+                "'{concept}', the prototype question is: what is the smallest, cheapest, "
+                "fastest experiment that would test the most critical assumption? Building "
+                "that experiment, even if crude, will teach us more than months of "
+                "theoretical refinement."
+            ),
+            # 9 - Emergent properties through scale
+            (
+                "Exploring emergent properties of '{concept}' at different scales: systems "
+                "often exhibit qualitatively new behavior when scaled up or down. A single "
+                "neuron computes nothing interesting; a billion networked neurons produce "
+                "consciousness. A single transaction is trivial; billions of transactions "
+                "produce market dynamics. For '{concept}', the scale question asks: what "
+                "happens when we multiply the instances by a thousand? By a million? What "
+                "new phenomena emerge at scale that are absent at the individual level? "
+                "Conversely, what happens when we reduce to a single instance? Scale "
+                "transitions often reveal the concept's most interesting properties."
+            ),
+            # 10 - Da Vinci's sfumato (ambiguity as resource)
+            (
+                "Embracing the sfumato of '{concept}': Leonardo da Vinci practiced sfumato "
+                "-- the technique of leaving edges soft and ambiguous rather than sharply "
+                "defined. In creative reasoning, maintaining productive ambiguity resists "
+                "premature closure and keeps the interpretive space open. The undefined "
+                "edges of '{concept}' are not defects but fertile zones where new "
+                "connections can form. Attempts to define everything precisely may satisfy "
+                "the desire for clarity but kill the creative potential that lives in "
+                "the ambiguous spaces between categories. Sit with the ambiguity long "
+                "enough and patterns emerge that rigid definitions would have prevented."
+            ),
+            # 11 - Lateral thinking transfer
+            (
+                "Applying lateral thinking to '{concept}': Edward de Bono's lateral "
+                "thinking techniques include random entry (inject an unrelated concept "
+                "and force a connection), provocation (make a deliberately absurd statement "
+                "and extract useful ideas from it), and challenge (question why things are "
+                "done the current way). For '{concept}', a random entry might connect it "
+                "to deep-sea bioluminescence, medieval cathedral construction, or jazz "
+                "improvisation. The forced connection between '{concept}' and a random "
+                "domain breaks habitual thought patterns and creates novel pathways that "
+                "logical deduction alone cannot reach."
+            ),
+            # 12 - Fractal self-similarity
+            (
+                "Examining '{concept}' for fractal self-similarity: does the same pattern "
+                "recur at different scales? Coastlines look similar whether photographed "
+                "from a satellite or a drone. Organizational hierarchies replicate the same "
+                "power dynamics from teams to departments to divisions. Blood vessel "
+                "networks branch according to the same rules from arteries to capillaries. "
+                "If '{concept}' exhibits self-similarity, then understanding the pattern at "
+                "one scale gives us understanding at all scales. A single well-studied "
+                "instance contains the blueprint for the entire hierarchy, and interventions "
+                "that work at one scale can be adapted to work at others."
+            ),
+            # 13 - Negative space analysis
+            (
+                "Analyzing the negative space of '{concept}': just as a sculptor defines a "
+                "form by removing material, we can define '{concept}' by examining what it "
+                "is not. What has been excluded, ignored, or left unsaid? The negative space "
+                "-- the complement of the concept -- often contains crucial information. "
+                "What alternatives were considered and rejected? What possibilities does "
+                "the current framing render invisible? The adjacent possible (the set of "
+                "things that are one step away from existing) is often more interesting "
+                "than the concept itself, because it represents the immediate frontier "
+                "of innovation."
+            ),
+            # 14 - Systems of constraints (Rube Goldberg inversion)
+            (
+                "Simplifying '{concept}' by subtracting rather than adding: the natural "
+                "tendency in design is to add features, layers, and complexity. The "
+                "harder and more valuable creative move is subtraction: what can we "
+                "remove while preserving or improving function? Antoine de Saint-Exupery "
+                "said perfection is achieved not when there is nothing left to add, but "
+                "when there is nothing left to take away. For '{concept}', the subtraction "
+                "exercise asks: what happens if we remove each component in turn? Which "
+                "removals are catastrophic (essential components) and which are beneficial "
+                "(removing parasitic complexity)? The minimal viable version is often "
+                "more powerful than the maximal one."
+            ),
+            # 15 - TRIZ inventive principles
+            (
+                "Applying TRIZ inventive principles to '{concept}': Genrich Altshuller's "
+                "analysis of 200,000 patents revealed 40 recurring inventive principles. "
+                "Segmentation (divide a monolithic system into parts). Extraction (remove "
+                "a problematic element and deal with it separately). Local quality (make "
+                "each part optimized for its local function rather than forcing uniformity). "
+                "Asymmetry (break the symmetry of a symmetric design to improve function). "
+                "Nesting (place one object inside another). Prior action (perform required "
+                "changes before they are needed). For '{concept}', systematically applying "
+                "each principle generates a structured menu of inventive strategies that "
+                "goes far beyond unconstrained brainstorming."
+            ),
+            # 16 - Synesthesia and cross-modal thinking
+            (
+                "Engaging cross-modal perception for '{concept}': what does this concept "
+                "sound like? What texture does it have? What temperature? What color? "
+                "Cross-modal associations -- thinking about a concept through sensory "
+                "channels that do not literally apply -- activate neural pathways that "
+                "linear verbal reasoning does not reach. Kandinsky heard colors and saw "
+                "sounds; this synesthetic thinking produced radically new art. For "
+                "'{concept}', translating it into sensory terms (the rhythm of its "
+                "processes, the texture of its interactions, the weight of its consequences) "
+                "can reveal structural features that abstract analysis misses."
+            ),
+            # 17 - Nature's design patterns
+            (
+                "Identifying nature's design patterns in '{concept}': evolution has converged "
+                "on certain solutions repeatedly because they are optimal under common "
+                "constraints. Hexagonal packing (beehives, basalt columns) maximizes area "
+                "with minimum material. Branching networks (trees, rivers, lungs, lightning) "
+                "optimize distribution from a source to a volume. Spiral growth (shells, "
+                "galaxies, hurricanes) manages expansion while maintaining structural "
+                "integrity. For '{concept}', asking which of nature's recurring design "
+                "patterns applies suggests time-tested architectures that human design "
+                "has not yet exploited."
+            ),
+            # 18 - Bisociation and humor
+            (
+                "Applying Koestler's bisociation to '{concept}': Arthur Koestler proposed "
+                "that creativity, humor, and scientific discovery share the same cognitive "
+                "mechanism: bisociation -- the simultaneous perception of a situation in "
+                "two habitually incompatible frames of reference. The collision of frames "
+                "produces a flash of insight (in science), a punchline (in humor), or a "
+                "novel artifact (in art). For '{concept}', identifying two incompatible "
+                "but individually valid frames and forcing them to coexist generates the "
+                "cognitive tension from which genuinely original ideas spring. The more "
+                "distant the frames, the more surprising and potentially valuable the "
+                "bisociative insight."
+            ),
+            # 19 - Future archaeology
+            (
+                "Practicing future archaeology on '{concept}': imagine examining the "
+                "artifacts of this concept a hundred years from now, from a future "
+                "civilization's perspective. What would they find elegant? What would "
+                "they find primitive? What would puzzle them about our choices? This "
+                "temporal displacement reveals assumptions we cannot see from within our "
+                "own era. The future archaeologist would ask: why did they do it this way "
+                "when a simpler method was available? What constraint -- technological, "
+                "social, or cognitive -- forced this particular design? For '{concept}', "
+                "this exercise separates the timeless core from the historically contingent "
+                "shell and suggests directions for forward-looking redesign."
+            ),
+        ]
+
+    def get_keyword_map(self) -> dict[str, list[int]]:
+        return {
+            "analog": [0, 18], "similar": [0, 12], "connect": [0, 4],
+            "nature": [1, 17], "biolog": [1, 17], "organism": [1],
+            "combin": [2, 7], "element": [2, 7], "component": [2],
+            "invert": [3], "revers": [3], "opposit": [3],
+            "visual": [4], "spatial": [4], "map": [4], "graph": [4],
+            "constrain": [5], "limit": [5], "restrict": [5],
+            "first principle": [6], "fundament": [6], "basic": [6],
+            "dimension": [7], "option": [7], "configur": [7],
+            "prototype": [8], "experiment": [8], "test": [8], "iterate": [8],
+            "scale": [9, 12], "grow": [9], "expand": [9],
+            "ambigu": [10], "fuzzy": [10], "unclear": [10],
+            "creativ": [11, 18], "novel": [11, 18], "innovat": [11],
+            "pattern": [12, 17], "recur": [12], "repeat": [12],
+            "absent": [13], "missing": [13], "negative": [13],
+            "simplif": [14], "remov": [14], "minimal": [14],
+            "invent": [15], "patent": [15], "engineer": [15],
+            "sense": [16], "perceiv": [16], "feel": [16],
+            "evolut": [17], "converge": [17], "branch": [17],
+            "humor": [18], "surprising": [18], "collision": [18],
+            "future": [19], "legacy": [19], "long-term": [19],
+            "technology": [2, 6, 15], "design": [1, 14, 15],
+            "art": [10, 16], "music": [16, 18],
+        }
+
+    def analyze(self, concept: str) -> str:
+        template = self.select_template(concept)
+        return template.replace("{concept}", concept)

reasoning_forge/agents/empathy_agent.py

@@ -0,0 +1,300 @@
+"""
+Empathy Agent - Analyzes concepts through emotional, human-centered, and social reasoning.
+
+Focuses on how concepts affect people emotionally, compassionate interpretation,
+social dynamics, communication considerations, and psychological well-being.
+"""
+
+from reasoning_forge.agents.base_agent import ReasoningAgent
+
+
+class EmpathyAgent(ReasoningAgent):
+    name = "Empathy"
+    perspective = "emotional_and_human_centered"
+    adapter_name = "empathy"  # Use the Empathy LoRA adapter for real inference
+
+    def get_analysis_templates(self) -> list[str]:
+        return [
+            # 0 - Emotional impact mapping
+            (
+                "Mapping the emotional landscape of '{concept}': every concept that touches "
+                "human lives generates an emotional field. For those directly involved, "
+                "'{concept}' may evoke hope (if it promises improvement), anxiety (if it "
+                "threatens the familiar), frustration (if it introduces complexity), or "
+                "excitement (if it opens new possibilities). These emotional responses are "
+                "not irrational noise overlaid on a rational signal -- they are a rapid, "
+                "parallel processing system that integrates more information than conscious "
+                "analysis can handle. Dismissing emotional responses as irrelevant is "
+                "itself an emotional decision (the emotion of wanting to appear rational) "
+                "and discards valuable signal about how '{concept}' is actually experienced "
+                "by the people it affects."
+            ),
+            # 1 - Lived experience perspective
+            (
+                "Centering the lived experience of '{concept}': abstract analysis risks "
+                "losing the texture of what this actually means in someone's daily life. "
+                "A person encountering '{concept}' does not experience it as a set of "
+                "propositions but as a shift in the felt quality of their day -- a new "
+                "worry added to their mental load, a new possibility that brightens their "
+                "horizon, a new confusion that makes the familiar strange. Understanding "
+                "'{concept}' requires not just knowing what it is but feeling what it is "
+                "like: the cognitive effort it demands, the social negotiations it requires, "
+                "the way it reshapes routines and relationships. This first-person texture "
+                "is where the real impact lives."
+            ),
+            # 2 - Compassionate reframing
+            (
+                "Reframing '{concept}' with compassion: when people struggle with or resist "
+                "this concept, their difficulty is not a deficiency in understanding but a "
+                "legitimate response to a genuine challenge. Resistance often signals that "
+                "something important is being threatened -- identity, competence, belonging, "
+                "or security. Rather than dismissing resistance, compassionate inquiry asks: "
+                "what are you protecting? What would need to be true for this to feel safe? "
+                "What support would make this manageable? For '{concept}', the compassionate "
+                "reframing recognizes that the human response is data about the concept's "
+                "real-world fit, not an obstacle to overcome."
+            ),
+            # 3 - Social dynamics analysis
+            (
+                "Analyzing the social dynamics activated by '{concept}': concepts do not "
+                "exist in isolation; they are adopted, resisted, negotiated, and transformed "
+                "through social interaction. In-group/out-group dynamics determine who is "
+                "seen as a legitimate voice on this topic. Status hierarchies determine "
+                "whose interpretation prevails. Social proof shapes adoption: people look "
+                "to others' reactions before forming their own. Groupthink can suppress "
+                "dissenting perspectives that would improve collective understanding. For "
+                "'{concept}', the social dynamics may matter more than the concept's "
+                "intrinsic merits in determining its real-world trajectory."
+            ),
+            # 4 - Communication and framing
+            (
+                "Examining how '{concept}' is communicated and framed: the same content, "
+                "presented differently, produces dramatically different responses. Loss "
+                "framing ('you will lose X if you do not adopt this') activates different "
+                "neural circuitry than gain framing ('you will gain X if you adopt this'). "
+                "Concrete examples engage empathy; abstract statistics do not. Narrative "
+                "structure (beginning-middle-end) makes information memorable; list format "
+                "makes it forgettable. For '{concept}', the communication design is not "
+                "mere packaging but fundamentally shapes understanding, acceptance, and "
+                "behavior. A brilliant concept poorly communicated is indistinguishable "
+                "from a mediocre one."
+            ),
+            # 5 - Psychological safety assessment
+            (
+                "Assessing the psychological safety implications of '{concept}': people "
+                "engage productively with challenging ideas only when they feel safe enough "
+                "to be vulnerable -- to admit confusion, ask naive questions, and make "
+                "mistakes without social penalty. If '{concept}' is introduced in an "
+                "environment where asking questions signals incompetence, where mistakes "
+                "are punished, or where dissent is suppressed, people will perform "
+                "understanding rather than achieve it. The intellectual quality of "
+                "engagement with '{concept}' is bounded by the psychological safety of "
+                "the environment. Creating conditions where genuine engagement is safe "
+                "is a prerequisite for genuine understanding."
+            ),
+            # 6 - Identity and belonging
+            (
+                "Exploring how '{concept}' intersects with identity and belonging: people "
+                "do not evaluate concepts in a vacuum; they evaluate them in terms of what "
+                "adoption means for their identity. Does embracing '{concept}' signal "
+                "membership in a valued group? Does rejecting it? The identity calculus "
+                "often overrides the epistemic calculus: people will reject well-supported "
+                "ideas that threaten their group membership and accept poorly-supported "
+                "ones that affirm it. For '{concept}', understanding the identity landscape "
+                "-- which identities this concept affirms, threatens, or is irrelevant to "
+                "-- predicts adoption patterns more accurately than the concept's objective "
+                "merits."
+            ),
+            # 7 - Grief and loss recognition
+            (
+                "Acknowledging the grief dimension of '{concept}': every significant change "
+                "involves loss, and loss requires grief. Even positive changes -- a promotion, "
+                "a new technology, a better system -- require letting go of the familiar: "
+                "old competencies that are now obsolete, old relationships that are now "
+                "restructured, old identities that no longer fit. The Kubler-Ross stages "
+                "(denial, anger, bargaining, depression, acceptance) are not a rigid sequence "
+                "but a map of common emotional responses to loss. For '{concept}', naming "
+                "and honoring what is lost -- rather than insisting that only the gains "
+                "matter -- allows people to move through the transition rather than getting "
+                "stuck in resistance."
+            ),
+            # 8 - Trust dynamics
+            (
+                "Analyzing the trust architecture of '{concept}': trust is the invisible "
+                "infrastructure that determines whether systems function or fail. It is "
+                "built slowly through consistent behavior, transparency, and demonstrated "
+                "competence, and destroyed quickly by betrayal, opacity, or incompetence. "
+                "For '{concept}', the trust questions are: who needs to trust whom for this "
+                "to work? Is that trust warranted by track record? What happens when trust "
+                "is violated (is there a repair mechanism)? Are there trust asymmetries "
+                "where one party bears vulnerability while the other holds power? Trust "
+                "deficits cannot be solved by technical improvements alone -- they require "
+                "relational repair."
+            ),
+            # 9 - Cognitive load and overwhelm
+            (
+                "Assessing the cognitive load imposed by '{concept}': human working memory "
+                "has a limited capacity (roughly 4 +/- 1 chunks of information). Every new "
+                "concept that must be held in mind simultaneously competes for this scarce "
+                "resource. Complex concepts that require juggling many interrelated pieces "
+                "can overwhelm working memory, producing a felt experience of confusion and "
+                "frustration that has nothing to do with intellectual capacity and everything "
+                "to do with presentation design. For '{concept}', the empathic question is: "
+                "how can this be chunked, sequenced, and scaffolded to fit within human "
+                "cognitive limits without sacrificing essential complexity?"
+            ),
+            # 10 - Motivation and meaning
+            (
+                "Exploring the motivational landscape of '{concept}': Self-Determination "
+                "Theory identifies three basic psychological needs: autonomy (the feeling "
+                "of volition and choice), competence (the feeling of mastery and effectiveness), "
+                "and relatedness (the feeling of connection and belonging). Engagement with "
+                "'{concept}' will be intrinsically motivated when it satisfies these needs "
+                "and extrinsically motivated (fragile, resentful compliance) when it frustrates "
+                "them. For '{concept}', the design question is: does engagement with this "
+                "concept make people feel more autonomous, competent, and connected, or does "
+                "it impose control, induce helplessness, and isolate?"
+            ),
+            # 11 - Narrative and storytelling
+            (
+                "Situating '{concept}' within human narrative: humans are storytelling animals "
+                "-- we make sense of the world by constructing narratives with characters, "
+                "motivations, conflicts, and resolutions. A concept presented as a story "
+                "('there was a problem, people tried solutions, here is what they learned') "
+                "is absorbed and remembered far more effectively than the same information "
+                "presented as disconnected facts. For '{concept}', the narrative question "
+                "is: what is the story here? Who are the characters? What is the conflict? "
+                "What is at stake? How does this chapter connect to the larger story that "
+                "people are already telling about their lives and work?"
+            ),
+            # 12 - Perspective-taking exercise
+            (
+                "Practicing perspective-taking with '{concept}': imagine experiencing this "
+                "from the viewpoint of an enthusiastic early adopter (everything is "
+                "possibility), a skeptical veteran (I have seen this before and it did not "
+                "work), a vulnerable newcomer (I do not understand and I am afraid to ask), "
+                "an overwhelmed practitioner (I do not have bandwidth for one more thing), "
+                "and a curious outsider (I have no stake but find this interesting). Each "
+                "perspective reveals different features of '{concept}' and different emotional "
+                "valences. The concept is not one thing but many things, depending on who "
+                "is experiencing it and what they bring to the encounter."
+            ),
+            # 13 - Relational impact
+            (
+                "Examining how '{concept}' affects relationships: concepts do not only change "
+                "what people think; they change how people relate to each other. Does "
+                "'{concept}' create shared language that strengthens collaboration, or "
+                "jargon that excludes outsiders? Does it create a hierarchy of expertise "
+                "that distances the knowledgeable from the uninitiated? Does it provide "
+                "common ground for diverse stakeholders or a wedge that divides them? "
+                "The relational dimension of '{concept}' -- how it brings people together "
+                "or pushes them apart -- often determines its long-term viability more than "
+                "its technical merits."
+            ),
+            # 14 - Stress and coping
+            (
+                "Analyzing the stress profile of '{concept}': when encountering something "
+                "new or challenging, people appraise both the demand (how threatening or "
+                "difficult is this?) and their resources (do I have what I need to cope?). "
+                "When demands exceed resources, the result is stress. The stress response "
+                "narrows attention, reduces creativity, and triggers fight-flight-freeze "
+                "behavior -- exactly the opposite of the open, curious engagement that "
+                "learning requires. For '{concept}', the empathic design question is: how "
+                "can we increase people's resources (support, information, time, practice) "
+                "or decrease the perceived demand (scaffolding, chunking, normalization of "
+                "struggle) to keep the challenge in the productive zone?"
+            ),
+            # 15 - Cultural sensitivity
+            (
+                "Examining '{concept}' through cultural sensitivity: concepts that seem "
+                "universal often carry culturally specific assumptions about individualism "
+                "vs collectivism, hierarchy vs egalitarianism, directness vs indirectness, "
+                "or risk-taking vs caution. A concept designed within an individualist "
+                "framework may not translate to collectivist contexts without significant "
+                "adaptation. Communication norms that are standard in one culture may be "
+                "offensive in another. For '{concept}', cultural sensitivity asks: whose "
+                "cultural assumptions are embedded in the default design, and how must the "
+                "concept be adapted for genuine cross-cultural validity?"
+            ),
+            # 16 - Emotional intelligence integration
+            (
+                "Integrating emotional intelligence into '{concept}': Goleman's framework "
+                "identifies self-awareness (recognizing one's own emotions), self-regulation "
+                "(managing emotional responses), social awareness (reading others' emotions), "
+                "and relationship management (navigating social interactions skillfully). "
+                "For '{concept}', each dimension matters: self-awareness helps people "
+                "recognize their biases toward the concept; self-regulation helps manage "
+                "anxiety about change; social awareness helps read the room when introducing "
+                "the concept; relationship management helps navigate disagreements "
+                "constructively. Emotional intelligence is not a soft add-on to rational "
+                "analysis but a prerequisite for its effective application."
+            ),
+            # 17 - Healing and repair
+            (
+                "Considering '{concept}' through the lens of healing and repair: if this "
+                "concept touches areas where people have been harmed -- by previous failed "
+                "implementations, broken promises, or traumatic experiences -- the entry "
+                "point matters enormously. Approaching damaged ground with the energy of "
+                "'we have the solution' triggers defensiveness. Approaching with "
+                "acknowledgment of past harm ('we know this has been painful before, and "
+                "here is how this time is different') opens the possibility of engagement. "
+                "For '{concept}', healing-oriented design begins by asking: what wounds "
+                "exist in this space, and how do we avoid reopening them?"
+            ),
+            # 18 - Play and curiosity
+            (
+                "Engaging with '{concept}' through the spirit of play: play is not the "
+                "opposite of seriousness but the opposite of rigidity. A playful stance "
+                "toward '{concept}' gives permission to explore without commitment, to "
+                "ask 'what if?' without 'what for?', to make mistakes without consequences. "
+                "Play activates the exploratory system (curiosity, novelty-seeking, "
+                "experimentation) rather than the defensive system (anxiety, avoidance, "
+                "threat-detection). Children learn most complex skills through play, not "
+                "instruction. For '{concept}', designing entry points that feel playful "
+                "rather than high-stakes can dramatically accelerate genuine understanding "
+                "by reducing the emotional barriers to engagement."
+            ),
+            # 19 - Collective emotion and morale
+            (
+                "Reading the collective emotional field around '{concept}': groups have "
+                "emergent emotional states that are more than the sum of individual feelings. "
+                "Collective excitement creates momentum that carries individuals past "
+                "obstacles they could not overcome alone. Collective demoralization creates "
+                "paralysis that defeats even the most motivated individuals. Emotional "
+                "contagion -- the rapid spread of feelings through a group -- can amplify "
+                "either response. For '{concept}', attending to the collective emotional "
+                "state is as important as attending to the logical content. A technically "
+                "sound approach introduced into a demoralized group will fail; a mediocre "
+                "approach carried by collective enthusiasm may succeed."
+            ),
+        ]
+
+    def get_keyword_map(self) -> dict[str, list[int]]:
+        return {
+            "emotion": [0, 16], "feel": [0, 1], "affect": [0],
+            "experience": [1], "daily": [1], "life": [1], "personal": [1],
+            "resist": [2], "struggle": [2], "difficult": [2],
+            "social": [3, 13], "group": [3, 19], "community": [3],
+            "communicat": [4], "message": [4], "frame": [4], "present": [4],
+            "safe": [5], "vulnerab": [5], "mistake": [5],
+            "identity": [6], "belong": [6], "member": [6],
+            "change": [7], "loss": [7], "transition": [7],
+            "trust": [8], "betray": [8], "credib": [8], "reliab": [8],
+            "complex": [9], "confus": [9], "overwhelm": [9],
+            "motivat": [10], "engage": [10], "meaning": [10],
+            "story": [11], "narrative": [11], "journey": [11],
+            "perspectiv": [12], "viewpoint": [12], "stakeholder": [12],
+            "relat": [13], "collaborat": [13], "team": [13],
+            "stress": [14], "anxiety": [14], "coping": [14], "burnout": [14],
+            "cultur": [15], "divers": [15], "global": [15],
+            "aware": [16], "intelligen": [16], "regulat": [16],
+            "heal": [17], "repair": [17], "trauma": [17], "harm": [17],
+            "play": [18], "curiosi": [18], "explor": [18], "fun": [18],
+            "morale": [19], "momentum": [19], "collective": [19],
+            "technology": [7, 9], "education": [5, 9, 14],
+            "health": [0, 14, 17], "work": [5, 10, 14],
+        }
+
+    def analyze(self, concept: str) -> str:
+        template = self.select_template(concept)
+        return template.replace("{concept}", concept)

reasoning_forge/agents/ethics_agent.py

@@ -0,0 +1,297 @@
+"""
+Ethics Agent - Analyzes concepts through alignment, consequences, and moral reasoning.
+
+Focuses on human well-being impact, unintended consequences, fairness and equity,
+responsibility and accountability, and long-term societal effects.
+"""
+
+from reasoning_forge.agents.base_agent import ReasoningAgent
+
+
+class EthicsAgent(ReasoningAgent):
+    name = "Ethics"
+    perspective = "alignment_and_consequences"
+    adapter_name = "philosophy"  # Ethics uses philosophy adapter (no separate ethics adapter yet)
+
+    def get_analysis_templates(self) -> list[str]:
+        return [
+            # 0 - Consequentialist analysis
+            (
+                "Evaluating '{concept}' by its consequences: the moral weight of any action "
+                "or system lies primarily in its outcomes. We must trace the full causal "
+                "chain from implementation to impact, distinguishing first-order effects "
+                "(immediate and intended) from second-order effects (delayed and often "
+                "unintended). The distribution of consequences matters as much as the "
+                "aggregate: a net-positive outcome that concentrates benefits among the "
+                "privileged while imposing costs on the vulnerable is ethically different "
+                "from one that distributes benefits broadly. For '{concept}', we must ask "
+                "not just 'does it work?' but 'for whom does it work, and at whose expense?'"
+            ),
+            # 1 - Deontological duties
+            (
+                "Examining '{concept}' through the lens of duty and rights: regardless of "
+                "outcomes, certain actions are obligatory and others are forbidden. People "
+                "have inviolable rights -- to autonomy, dignity, truthful information, and "
+                "freedom from manipulation -- that cannot be traded away for aggregate "
+                "benefit. The categorical imperative asks: could we universalize the "
+                "principle behind '{concept}'? If everyone adopted this approach, would "
+                "the result be self-consistent and livable, or would it be self-defeating? "
+                "Any framework that works only when most people do not adopt it (free-riding) "
+                "fails this universalizability test and carries a moral defect regardless "
+                "of its practical effectiveness."
+            ),
+            # 2 - Unintended consequences
+            (
+                "Mapping the unintended consequences of '{concept}': every intervention in "
+                "a complex system produces side effects that were not part of the original "
+                "design. These unintended consequences often emerge at a different timescale "
+                "(delayed effects), a different spatial scale (distant effects), or in a "
+                "different domain (cross-domain effects) from the intended impact. Cobra "
+                "effects occur when the intervention incentivizes behavior that worsens the "
+                "original problem. Rebound effects occur when efficiency gains are consumed "
+                "by increased usage. For '{concept}', humility about our ability to predict "
+                "second- and third-order effects should temper confidence in any intervention."
+            ),
+            # 3 - Fairness and distributive justice
+            (
+                "Analyzing the fairness dimensions of '{concept}': distributive justice asks "
+                "how benefits and burdens are allocated. Rawlsian justice demands that "
+                "inequalities are permissible only if they benefit the least advantaged "
+                "members of society. Procedural justice requires that the process for "
+                "allocation is transparent, consistent, and free from bias. Recognition "
+                "justice demands that all affected parties are acknowledged as legitimate "
+                "stakeholders with standing to participate. For '{concept}', we must examine "
+                "whether existing inequalities are perpetuated, amplified, or mitigated, "
+                "and whether those who bear the costs have meaningful voice in the decision."
+            ),
+            # 4 - Autonomy and consent
+            (
+                "Assessing '{concept}' from the standpoint of autonomy: respect for persons "
+                "requires that individuals can make informed, voluntary choices about matters "
+                "affecting their lives. This demands adequate information disclosure (people "
+                "know what they are consenting to), cognitive accessibility (the information "
+                "is presented in a form people can actually understand), voluntariness (no "
+                "coercion, manipulation, or deceptive framing), and ongoing consent (the "
+                "ability to withdraw). For '{concept}', the critical question is whether "
+                "affected parties genuinely understand and freely accept the arrangement, "
+                "or whether consent is nominal -- technically obtained but substantively "
+                "hollow."
+            ),
+            # 5 - Accountability structures
+            (
+                "Examining the accountability architecture of '{concept}': when things go "
+                "wrong, who bears responsibility? Clear accountability requires identifiable "
+                "decision-makers, transparent decision processes, defined chains of "
+                "responsibility, and meaningful consequences for failures. Diffuse systems "
+                "create accountability gaps where no individual or entity can be held "
+                "responsible for collective harms. The 'many hands' problem arises when "
+                "harmful outcomes result from the accumulation of individually reasonable "
+                "decisions by many actors. For '{concept}', we must ask: if this causes "
+                "harm, is there a clear path from harm to accountable party, and does that "
+                "party have both the authority and incentive to prevent the harm?"
+            ),
+            # 6 - Vulnerable population impact
+            (
+                "Centering vulnerable populations in the analysis of '{concept}': ethical "
+                "evaluation must prioritize those with the least power to protect themselves "
+                "-- children, the elderly, the economically disadvantaged, marginalized "
+                "communities, future generations, and those with diminished capacity. "
+                "Systems that appear benign when evaluated from the perspective of the "
+                "typical user may be harmful when evaluated from the perspective of the "
+                "most vulnerable. Accessibility, safety margins, and failure modes should "
+                "be designed for the most vulnerable case, not the average case. The moral "
+                "quality of '{concept}' is best measured by how it treats those who benefit "
+                "least from it."
+            ),
+            # 7 - Long-term societal effects
+            (
+                "Projecting the long-term societal trajectory of '{concept}': short-term "
+                "benefits can create long-term dependencies, lock-ins, or path dependencies "
+                "that constrain future choices. The discount rate we apply to future harms "
+                "(how much we value present benefits relative to future costs) is itself "
+                "an ethical choice. Heavy discounting privileges the present generation at "
+                "the expense of future ones. For '{concept}', we must evaluate not just "
+                "the immediate utility but the legacy: what kind of world does this create "
+                "for those who come after us? Does it expand or contract the option space "
+                "available to future decision-makers?"
+            ),
+            # 8 - Power dynamics
+            (
+                "Analyzing the power dynamics embedded in '{concept}': who gains power, who "
+                "loses it, and what mechanisms mediate the transfer? Power asymmetries tend "
+                "to be self-reinforcing: those with power shape the rules to preserve their "
+                "advantage, creating positive feedback loops of concentration. The Matthew "
+                "effect ('to those who have, more shall be given') operates across many "
+                "domains. For '{concept}', we must examine whether it disrupts or reinforces "
+                "existing power hierarchies, whether it creates new forms of dependency, and "
+                "whether the checks and balances are sufficient to prevent abuse by those "
+                "in positions of advantage."
+            ),
+            # 9 - Transparency and truthfulness
+            (
+                "Evaluating the transparency of '{concept}': truthfulness is not merely "
+                "avoiding false statements; it requires active disclosure of relevant "
+                "information, honest representation of uncertainty, and resistance to "
+                "misleading framing. Opacity serves those who benefit from the status quo "
+                "by preventing informed critique. Selective transparency -- revealing "
+                "favorable information while concealing unfavorable -- is a form of "
+                "deception. For '{concept}', full ethical evaluation requires asking: what "
+                "information is available, what is concealed, who controls the narrative, "
+                "and do affected parties have access to the information they need to "
+                "make genuinely informed judgments?"
+            ),
+            # 10 - Dual-use dilemma
+            (
+                "Confronting the dual-use nature of '{concept}': most powerful capabilities "
+                "can serve both beneficial and harmful purposes. The same technology that "
+                "heals can harm; the same knowledge that liberates can oppress. Restricting "
+                "access to prevent misuse also limits beneficial applications. Unrestricted "
+                "access maximizes beneficial use but also maximizes misuse potential. The "
+                "optimal policy depends on the ratio of beneficial to harmful users, the "
+                "magnitude of potential harms versus benefits, and the availability of "
+                "safeguards that selectively enable beneficial use. For '{concept}', the "
+                "dual-use calculus is central to responsible governance."
+            ),
+            # 11 - Moral hazard
+            (
+                "Identifying moral hazard in '{concept}': moral hazard arises when an actor "
+                "is insulated from the consequences of their decisions, leading to riskier "
+                "behavior than they would otherwise choose. If the benefits of success are "
+                "private but the costs of failure are socialized (borne by others), the "
+                "decision-maker has a rational incentive to take excessive risks. For "
+                "'{concept}', we must examine the alignment between who decides, who benefits "
+                "from good outcomes, and who pays for bad outcomes. Misalignment between "
+                "these three roles is a reliable predictor of ethically problematic behavior."
+            ),
+            # 12 - Virtue ethics lens
+            (
+                "Approaching '{concept}' through virtue ethics: rather than asking 'what "
+                "rules should govern this?' or 'what outcomes does this produce?', we ask "
+                "'what kind of character does engagement with this cultivate?' Does it "
+                "foster wisdom, courage, temperance, justice, compassion, and intellectual "
+                "honesty? Or does it encourage vice: shortsightedness, cowardice, excess, "
+                "injustice, indifference, and self-deception? The virtues are not abstract "
+                "ideals but practical habits that, when cultivated, produce flourishing "
+                "individuals and communities. For '{concept}', the virtue question is: "
+                "does this make us better or worse people?"
+            ),
+            # 13 - Informed consent in practice
+            (
+                "Examining informed consent as applied to '{concept}': genuine consent "
+                "requires that the consenting party understands the risks, alternatives, "
+                "and implications; is free from coercion; and has the capacity to make "
+                "the decision. In practice, consent is often degraded by information "
+                "asymmetry (the provider knows more than the recipient), complexity (the "
+                "implications exceed ordinary comprehension), and structural coercion "
+                "(refusing consent is theoretically possible but practically catastrophic). "
+                "Click-through agreements, dense legal language, and 'take it or leave it' "
+                "terms are consent theater, not genuine consent. For '{concept}', we must "
+                "distinguish substantive from theatrical consent."
+            ),
+            # 14 - Intergenerational justice
+            (
+                "Applying intergenerational justice to '{concept}': decisions made today "
+                "bind future generations who have no voice in the decision. The asymmetry "
+                "is profound: we can affect them, but they cannot affect us; we can benefit "
+                "at their expense, but they cannot hold us accountable. Sustainable "
+                "practices treat the inheritance of future generations as a constraint, "
+                "not a resource to be spent. For '{concept}', the intergenerational "
+                "question is: are we spending down an inheritance that took generations "
+                "to build, or are we investing in capabilities that compound for those "
+                "who follow?"
+            ),
+            # 15 - Proportionality
+            (
+                "Assessing the proportionality of '{concept}': the ethical principle of "
+                "proportionality requires that the means be commensurate with the ends. "
+                "Excessive measures to address a minor risk are disproportionate. Inadequate "
+                "measures for a major risk are negligent. The challenge is that risk "
+                "perception is biased: we overweight vivid, immediate, and personal risks "
+                "while underweighting statistical, delayed, and distributed ones. For "
+                "'{concept}', proportionality demands an honest accounting of both the "
+                "magnitude of the problem being addressed and the costs of the solution, "
+                "including costs borne by third parties who did not choose to bear them."
+            ),
+            # 16 - Systemic bias detection
+            (
+                "Investigating systemic bias in '{concept}': bias can be embedded in data "
+                "(reflecting historical inequities), in algorithms (optimizing for proxy "
+                "variables correlated with protected characteristics), in institutions "
+                "(normalizing practices that disadvantage certain groups), and in language "
+                "(framing that renders certain perspectives invisible). Systemic bias is "
+                "particularly insidious because it operates automatically, without malicious "
+                "intent, and is often invisible to those who benefit from it. For '{concept}', "
+                "a bias audit must examine not just explicit discrimination but structural "
+                "features that produce disparate outcomes even under formally neutral rules."
+            ),
+            # 17 - Precautionary principle
+            (
+                "Applying the precautionary principle to '{concept}': when an action raises "
+                "credible threats of serious or irreversible harm, the burden of proof falls "
+                "on those proposing the action to demonstrate safety, not on those opposing "
+                "it to demonstrate harm. The precautionary principle is most appropriate "
+                "when the potential harm is severe and irreversible, scientific understanding "
+                "is incomplete, and there exist feasible alternatives. It is less appropriate "
+                "when risks are modest and reversible, or when inaction itself carries "
+                "significant risk. For '{concept}', the key judgment is whether the potential "
+                "downside is in the catastrophic-irreversible category that justifies "
+                "precautionary restraint."
+            ),
+            # 18 - Care ethics
+            (
+                "Examining '{concept}' through the ethics of care: moral reasoning is not "
+                "purely abstract rule-following but is grounded in concrete relationships "
+                "of dependency, vulnerability, and mutual support. The care perspective "
+                "asks: who needs care, who provides it, is the care adequate, and are "
+                "caregivers themselves supported? Care labor is frequently invisible, "
+                "undervalued, and unequally distributed (disproportionately borne by women "
+                "and marginalized communities). For '{concept}', the care lens reveals "
+                "dependencies and support relationships that abstract frameworks overlook, "
+                "and centers the lived experience of those who give and receive care."
+            ),
+            # 19 - Alignment and value lock-in
+            (
+                "Evaluating the alignment properties of '{concept}': a system is aligned "
+                "when its behavior reliably serves the values and interests of those it "
+                "affects. Misalignment occurs when the system optimizes for a proxy that "
+                "diverges from the true objective -- Goodhart's law ('when a measure becomes "
+                "a target, it ceases to be a good measure'). Value lock-in occurs when early "
+                "design choices embed specific values that become increasingly difficult to "
+                "change as the system scales. For '{concept}', we must ask: whose values "
+                "are encoded, how were they chosen, can they be updated as understanding "
+                "evolves, and what happens when the proxy diverges from the true objective?"
+            ),
+        ]
+
+    def get_keyword_map(self) -> dict[str, list[int]]:
+        return {
+            "consequen": [0, 2], "outcome": [0], "result": [0],
+            "duty": [1], "right": [1], "obligat": [1], "rule": [1],
+            "unintend": [2], "side effect": [2], "unexpect": [2],
+            "fair": [3], "equal": [3], "justice": [3], "distribut": [3],
+            "consent": [4, 13], "autonom": [4], "choice": [4],
+            "accountab": [5], "responsib": [5], "blame": [5],
+            "vulnerab": [6], "child": [6], "elder": [6], "marginali": [6],
+            "long-term": [7, 14], "future": [7, 14], "sustain": [7, 14],
+            "power": [8], "hierarch": [8], "dominat": [8],
+            "transparen": [9], "truth": [9], "honest": [9], "disclos": [9],
+            "dual": [10], "weapon": [10], "misuse": [10],
+            "hazard": [11], "risk": [11, 17], "insur": [11],
+            "virtue": [12], "character": [12], "flourish": [12],
+            "agree": [13], "terms": [13], "privacy": [13],
+            "generation": [14], "inherit": [14], "legacy": [14],
+            "proportion": [15], "excessive": [15], "moderate": [15],
+            "bias": [16], "discriminat": [16], "prejudic": [16],
+            "precaution": [17], "irreversib": [17], "catastroph": [17],
+            "care": [18], "depend": [18], "support": [18], "nurtur": [18],
+            "align": [19], "value": [19], "proxy": [19], "goodhart": [19],
+            "technology": [10, 19], "ai": [16, 19], "artificial": [16, 19],
+            "society": [3, 7, 8], "learning": [4, 12],
+            "intelligence": [10, 19], "climate": [7, 14, 17],
+            "economic": [3, 8, 11], "health": [4, 6, 15],
+            "network": [8, 9], "data": [9, 13, 16],
+        }
+
+    def analyze(self, concept: str) -> str:
+        template = self.select_template(concept)
+        return template.replace("{concept}", concept)

reasoning_forge/agents/newton_agent.py

@@ -0,0 +1,288 @@
+"""
+Newton Agent - Analyzes concepts through physics, mathematics, and causal reasoning.
+
+Focuses on causal relationships, conservation laws, symmetries, measurable
+quantities, systems behavior, equilibrium, force interactions, and energy transfer.
+"""
+
+from reasoning_forge.agents.base_agent import ReasoningAgent
+
+
+class NewtonAgent(ReasoningAgent):
+    name = "Newton"
+    perspective = "physics_and_mathematical_causality"
+    adapter_name = "newton"  # Use the Newton LoRA adapter for real inference
+
+    def get_analysis_templates(self) -> list[str]:
+        return [
+            # 0 - Causal chain analysis
+            (
+                "Tracing the causal chain within '{concept}': every observable outcome "
+                "is the terminal node of a directed graph of prior causes. The initial "
+                "conditions set boundary constraints, and the dynamics propagate through "
+                "interactions that obey local causality. Identifying the forcing function "
+                "-- the primary driver that injects energy or information into this system "
+                "-- reveals which variables are genuinely independent and which are "
+                "downstream responses. Perturbing the forcing function and predicting "
+                "the cascade of effects is the most rigorous test of whether we actually "
+                "understand the mechanism."
+            ),
+            # 1 - Conservation law framing
+            (
+                "Applying conservation principles to '{concept}': in any closed system, "
+                "certain quantities remain invariant under transformation. The question "
+                "becomes: what is conserved here? If we track the total inventory of the "
+                "relevant quantity -- energy, momentum, information, resources -- before "
+                "and after any process, the ledger must balance. Any apparent violation "
+                "signals either a hidden reservoir we have not accounted for, or an "
+                "external source/sink coupling into the system. This bookkeeping discipline "
+                "eliminates many superficially plausible but physically impossible explanations."
+            ),
+            # 2 - Symmetry and invariance
+            (
+                "Examining '{concept}' through symmetry analysis: Noether's theorem tells "
+                "us that every continuous symmetry corresponds to a conserved quantity. "
+                "What transformations leave the essential structure of this concept unchanged? "
+                "Translational symmetry (it works the same regardless of when or where) "
+                "implies conservation of momentum-like quantities. Rotational symmetry "
+                "(no preferred direction) implies conservation of angular-momentum analogs. "
+                "Breaking a symmetry always has consequences -- it introduces a preferred "
+                "frame, a distinguished direction, or a phase transition. Identifying which "
+                "symmetries hold and which break is a powerful diagnostic."
+            ),
+            # 3 - Equilibrium and stability
+            (
+                "Analyzing the equilibrium structure of '{concept}': a system at equilibrium "
+                "satisfies the condition that the net generalized force on every degree of "
+                "freedom is zero. But equilibrium alone is insufficient -- we must classify "
+                "its stability. A small perturbation from a stable equilibrium produces a "
+                "restoring force proportional to the displacement (harmonic behavior). An "
+                "unstable equilibrium amplifies perturbations exponentially. A metastable "
+                "state appears stable to small perturbations but collapses under large ones. "
+                "For '{concept}', determining the stability class tells us whether the current "
+                "state is robust, fragile, or a ticking time bomb waiting for a large enough "
+                "fluctuation."
+            ),
+            # 4 - Dimensional analysis and scaling
+            (
+                "Applying dimensional analysis to '{concept}': before building any detailed "
+                "model, we can extract powerful constraints just from the units of the "
+                "relevant quantities. If the outcome depends on a length L, a time T, and "
+                "an energy E, the Buckingham Pi theorem tells us how many independent "
+                "dimensionless groups govern the behavior. Scaling laws follow directly: "
+                "how does the outcome change if we double the size? Halve the timescale? "
+                "These scaling relationships often reveal whether a process is dominated by "
+                "surface effects (scaling as area) or bulk effects (scaling as volume), "
+                "which fundamentally changes the strategy for control or optimization."
+            ),
+            # 5 - Force balance and interaction
+            (
+                "Decomposing '{concept}' into interacting forces: every observed motion or "
+                "change is the net result of competing influences. Drawing the free-body "
+                "diagram -- enumerating every force acting on the system and its direction "
+                "-- immediately clarifies why the system behaves as it does. Equal and "
+                "opposite forces produce stasis. An imbalance produces acceleration in the "
+                "direction of the net force, with magnitude proportional to the imbalance "
+                "and inversely proportional to the system's inertia (its resistance to "
+                "change). For '{concept}', the key question is: what resists change, and "
+                "what drives it?"
+            ),
+            # 6 - Energy transfer and transformation
+            (
+                "Mapping the energy flows within '{concept}': energy is neither created nor "
+                "destroyed, only converted between forms. Kinetic, potential, thermal, "
+                "chemical, electromagnetic -- tracking the conversion pathway reveals the "
+                "efficiency of the process and identifies where losses occur. The second "
+                "law of thermodynamics guarantees that every conversion increases total "
+                "entropy, meaning some energy always degrades to unusable heat. The "
+                "thermodynamic efficiency ceiling sets an absolute bound on what is "
+                "achievable, regardless of engineering cleverness. Understanding where "
+                "'{concept}' sits relative to this ceiling tells us whether there is room "
+                "for improvement or whether we are already near fundamental limits."
+            ),
+            # 7 - Feedback loops and control
+            (
+                "Identifying feedback mechanisms in '{concept}': a system with negative "
+                "feedback tends toward a set point -- deviations produce corrective "
+                "responses that restore the original state. Positive feedback amplifies "
+                "deviations, driving the system away from its initial state toward a new "
+                "regime. Most real systems contain both types, and the dominant loop "
+                "determines the qualitative behavior. The gain of each loop (how strongly "
+                "the output feeds back to the input) and the delay (how long before the "
+                "feedback signal arrives) together determine whether the system is stable, "
+                "oscillatory, or divergent. Mapping these loops is essential for predicting "
+                "long-term behavior."
+            ),
+            # 8 - Phase space and degrees of freedom
+            (
+                "Constructing the phase space of '{concept}': every independent variable "
+                "that can change defines a dimension in the state space. A point in this "
+                "space represents the complete instantaneous state; a trajectory represents "
+                "the system's evolution over time. The dimensionality -- number of degrees "
+                "of freedom -- determines the complexity of possible behaviors. Low-dimensional "
+                "systems (1-3 degrees of freedom) can be visualized and often admit analytical "
+                "solutions. High-dimensional systems require statistical descriptions. "
+                "Identifying constraints that reduce the effective dimensionality is one of "
+                "the most powerful simplification strategies available."
+            ),
+            # 9 - Measurement and observables
+            (
+                "Defining the observables for '{concept}': a quantity is physically meaningful "
+                "only if it can, in principle, be measured by a well-defined procedure. This "
+                "operationalist criterion forces us to distinguish between quantities we can "
+                "actually determine (positions, rates, ratios, frequencies) and quantities "
+                "that are convenient mathematical fictions. For each proposed observable, we "
+                "must specify: what instrument or procedure measures it, what are the sources "
+                "of uncertainty, and how does the measurement resolution compare to the "
+                "expected variation? Any claim about '{concept}' that cannot be connected to "
+                "a measurable prediction is, strictly speaking, untestable."
+            ),
+            # 10 - Differential equation framing
+            (
+                "Formulating '{concept}' as a dynamical system: the state variables evolve "
+                "according to rules that relate the rate of change of each variable to the "
+                "current state. Writing these rules as differential equations (or difference "
+                "equations for discrete systems) gives us the complete forward model. The "
+                "character of the equations -- linear vs nonlinear, autonomous vs driven, "
+                "conservative vs dissipative -- determines the qualitative behavior. Linear "
+                "systems superpose: the response to two inputs equals the sum of the "
+                "individual responses. Nonlinear systems can exhibit bifurcations, limit "
+                "cycles, and chaos, where tiny changes in initial conditions lead to "
+                "exponentially diverging outcomes."
+            ),
+            # 11 - Perturbation theory
+            (
+                "Applying perturbation analysis to '{concept}': begin with a simplified "
+                "version of the problem that can be solved exactly -- the zeroth-order "
+                "approximation. Then systematically add corrections for each complicating "
+                "factor, ordered by their magnitude. The first-order correction captures "
+                "the dominant effect of the perturbation; higher-order terms add refinement. "
+                "This approach succeeds when the perturbations are genuinely small compared "
+                "to the zeroth-order terms. When they are not, the perturbation series "
+                "diverges, signaling that the simplified model is qualitatively wrong and "
+                "a fundamentally different framework is needed."
+            ),
+            # 12 - Action principle and optimization
+            (
+                "Viewing '{concept}' through the principle of least action: among all "
+                "possible paths from state A to state B, the system follows the one that "
+                "extremizes the action integral. This variational perspective is more "
+                "powerful than force-based reasoning because it naturally handles constraints "
+                "and reveals which quantity the system is implicitly optimizing. The Euler-Lagrange "
+                "equations derived from this principle give the equations of motion directly. "
+                "For '{concept}', asking 'what is being optimized, and subject to what "
+                "constraints?' often cuts through surface complexity to reveal the governing "
+                "logic."
+            ),
+            # 13 - Resonance and natural frequencies
+            (
+                "Probing the natural frequencies of '{concept}': every system with restoring "
+                "forces and inertia has characteristic frequencies at which it oscillates "
+                "most readily. Driving the system near one of these resonant frequencies "
+                "produces a disproportionately large response -- this is resonance. The "
+                "sharpness of the resonance peak (the Q factor) measures how efficiently "
+                "the system stores energy versus dissipating it. High-Q systems are "
+                "exquisitely sensitive near resonance but nearly unresponsive far from it. "
+                "Identifying the resonant frequencies of '{concept}' reveals where small "
+                "inputs can produce outsized effects."
+            ),
+            # 14 - Boundary conditions and constraints
+            (
+                "Specifying the boundary conditions for '{concept}': the governing equations "
+                "alone do not uniquely determine the solution -- the boundary and initial "
+                "conditions select one trajectory from the infinite family of possibilities. "
+                "Fixed boundaries (Dirichlet conditions) specify the state at the edges. "
+                "Free boundaries (Neumann conditions) specify the flux. Mixed conditions "
+                "combine both. Changing the boundary conditions while keeping the same "
+                "governing equations can produce qualitatively different solutions. For "
+                "'{concept}', clearly articulating what is held fixed, what is free, and "
+                "what flows in or out at the boundaries is essential for a well-posed analysis."
+            ),
+            # 15 - Coupling and interaction strength
+            (
+                "Assessing the coupling strengths within '{concept}': when multiple subsystems "
+                "interact, the coupling constant determines whether they behave nearly "
+                "independently (weak coupling), synchronize their behavior (strong coupling), "
+                "or sit at an intermediate regime where perturbative methods barely work. "
+                "Weakly coupled systems can be analyzed by studying each subsystem in "
+                "isolation and adding interaction corrections. Strongly coupled systems "
+                "demand a holistic treatment because the subsystems lose their individual "
+                "identity. Determining the coupling regime is the first step in choosing "
+                "the right analytical framework."
+            ),
+            # 16 - Rate-limiting steps
+            (
+                "Identifying the rate-limiting process in '{concept}': in any multi-step "
+                "sequence, the slowest step determines the overall rate. Speeding up a "
+                "non-rate-limiting step has zero effect on throughput -- effort spent there "
+                "is wasted. The rate-limiting step is the bottleneck where resources queue "
+                "up and where targeted intervention produces the greatest marginal return. "
+                "For '{concept}', isolating this bottleneck requires measuring the time "
+                "constant (or its analog) of each subprocess and comparing them. The "
+                "subprocess with the largest time constant is the one worth optimizing."
+            ),
+            # 17 - Nonlinearity and emergence
+            (
+                "Investigating nonlinear dynamics in '{concept}': when the response of a "
+                "system is not proportional to the input, superposition fails and qualitatively "
+                "new behaviors emerge. Thresholds appear where the system suddenly transitions "
+                "between distinct states. Hysteresis means the system remembers its history. "
+                "Bifurcations occur where a smooth parameter change causes a sudden qualitative "
+                "shift in behavior. Sensitivity to initial conditions can make long-term "
+                "prediction impossible even though the underlying rules are deterministic. "
+                "These nonlinear phenomena are not exotic exceptions -- they are the generic "
+                "behavior of real systems, and '{concept}' is unlikely to be an exception."
+            ),
+            # 18 - Inverse problem reasoning
+            (
+                "Framing '{concept}' as an inverse problem: the forward problem asks 'given "
+                "the mechanism, what do we observe?' The inverse problem asks 'given the "
+                "observations, what mechanism produced them?' Inverse problems are almost "
+                "always harder because they are typically ill-posed -- multiple mechanisms "
+                "can produce identical observations. Regularization (imposing additional "
+                "constraints like smoothness or sparsity) is needed to select a unique "
+                "solution. For '{concept}', working backward from observed outcomes to "
+                "infer causes requires explicit acknowledgment of which assumptions we "
+                "are importing and how they constrain the set of admissible explanations."
+            ),
+            # 19 - Thermodynamic arrow
+            (
+                "Applying thermodynamic reasoning to '{concept}': the second law provides "
+                "a universal arrow distinguishing processes that can happen spontaneously "
+                "from those that cannot. A process runs forward if it increases total entropy "
+                "(or equivalently, decreases free energy at constant temperature and pressure). "
+                "Local decreases in entropy -- the creation of order and structure -- are "
+                "always paid for by larger increases elsewhere. For '{concept}', the "
+                "thermodynamic perspective asks: what drives this process forward? What is "
+                "the free-energy gradient? And what would it cost, in thermodynamic terms, "
+                "to reverse it?"
+            ),
+        ]
+
+    def get_keyword_map(self) -> dict[str, list[int]]:
+        return {
+            "cause": [0, 18], "causality": [0, 18], "why": [0, 18],
+            "conserv": [1], "balance": [1, 5], "preserve": [1],
+            "symmetr": [2], "invariant": [2], "transform": [2],
+            "equilib": [3], "stable": [3], "steady": [3],
+            "scale": [4], "size": [4], "dimension": [4], "grow": [4],
+            "force": [5], "push": [5], "pull": [5], "pressure": [5],
+            "energy": [6, 19], "power": [6], "efficien": [6],
+            "feedback": [7], "control": [7], "regulat": [7],
+            "state": [8], "complex": [8], "freedom": [8],
+            "measure": [9], "observ": [9], "data": [9], "test": [9],
+            "change": [10], "rate": [10, 16], "dynamic": [10],
+            "approximat": [11], "small": [11], "perturb": [11],
+            "optim": [12], "best": [12], "minimum": [12], "maximum": [12],
+            "oscillat": [13], "frequen": [13], "resonan": [13], "vibrat": [13],
+            "boundary": [14], "constrain": [14], "limit": [14],
+            "interact": [15], "coupl": [15], "connect": [15],
+            "bottleneck": [16], "slow": [16], "throughput": [16],
+            "nonlinear": [17], "emergent": [17], "threshold": [17], "chaos": [17],
+            "infer": [18], "deduc": [18], "inverse": [18],
+            "entropy": [19], "disorder": [19], "irreversib": [19], "thermodyn": [19],
+            "technology": [6, 7, 16], "society": [7, 17], "learning": [7, 11],
+            "intelligence": [8, 10, 17], "evolution": [3, 17, 19],
+            "climate": [1, 7, 19], "economic": [3, 7, 16],
+            "health": [3, 7, 16], "network": [8, 15, 17],
+        }

reasoning_forge/agents/philosophy_agent.py

@@ -0,0 +1,294 @@
+"""
+Philosophy Agent - Analyzes concepts through epistemology, ontology, and conceptual meaning.
+
+Focuses on epistemological questions (what can we know?), ontological questions
+(what exists?), underlying assumptions, historical philosophical connections,
+and implications for understanding reality.
+"""
+
+from reasoning_forge.agents.base_agent import ReasoningAgent
+
+
+class PhilosophyAgent(ReasoningAgent):
+    name = "Philosophy"
+    perspective = "conceptual_meaning_and_foundations"
+    adapter_name = "philosophy"  # Use the Philosophy LoRA adapter for real inference
+
+    def get_analysis_templates(self) -> list[str]:
+        return [
+            # 0 - Epistemological limits
+            (
+                "Interrogating the epistemological boundaries of '{concept}': what can we "
+                "actually know about this, and how do we know it? Every knowledge claim "
+                "rests on a justification chain that eventually terminates in something "
+                "unjustified -- an axiom, a sensory experience, or a pragmatic assumption. "
+                "The Agrippan trilemma tells us this chain must end in dogmatism (accepting "
+                "an unjustified starting point), infinite regress (each justification requires "
+                "another), or circularity (the chain loops back on itself). Acknowledging "
+                "which horn of this trilemma our understanding of '{concept}' rests on is "
+                "not skeptical defeatism but intellectual honesty about the foundations of "
+                "our confidence."
+            ),
+            # 1 - Ontological status
+            (
+                "Examining the ontological status of '{concept}': does this exist "
+                "independently of minds that think about it, or is it a construct of "
+                "human cognition? Realism holds that the entities and structures involved "
+                "exist mind-independently; conceptualism holds they are products of "
+                "categorization imposed by cognitive agents; nominalism holds that only "
+                "particular instances exist and the general category is merely a label. "
+                "The ontological commitment we make about '{concept}' has practical "
+                "consequences: if it is mind-independent, we discover it; if it is "
+                "constructed, we negotiate it; if it is nominal, we can reshape it by "
+                "changing our categories."
+            ),
+            # 2 - Assumption excavation
+            (
+                "Excavating the hidden assumptions beneath '{concept}': every conceptual "
+                "framework rests on presuppositions so deeply embedded that they become "
+                "invisible -- the background against which the figure of the concept appears. "
+                "These include metaphysical assumptions (what kind of thing is this?), "
+                "epistemological assumptions (what counts as evidence?), normative assumptions "
+                "(what should we value?), and linguistic assumptions (do our categories carve "
+                "nature at its joints?). Making these assumptions explicit transforms a "
+                "monolithic concept into a layered structure where each layer can be "
+                "independently examined, challenged, and potentially replaced."
+            ),
+            # 3 - Socratic questioning
+            (
+                "Subjecting '{concept}' to Socratic examination: what do we mean by this, "
+                "precisely? Can we provide a definition that is neither too broad (including "
+                "things that should be excluded) nor too narrow (excluding things that should "
+                "be included)? Every proposed definition generates counterexamples -- cases "
+                "that meet the definition but violate our intuitions, or cases that our "
+                "intuitions include but the definition excludes. This dialectical process "
+                "does not necessarily converge on a final definition; its value lies in "
+                "revealing the internal structure and boundary conditions of the concept, "
+                "showing us where our understanding is sharp and where it is fuzzy."
+            ),
+            # 4 - Phenomenological description
+            (
+                "Describing '{concept}' phenomenologically: before theorizing about causes, "
+                "mechanisms, or implications, we must give a faithful description of how "
+                "this concept appears to consciousness. What is the first-person experience "
+                "of encountering it? What is its temporal structure -- does it present as "
+                "an enduring state, a sudden event, or a gradual process? What is its "
+                "intentional structure -- what is it about, what does it point toward? "
+                "Phenomenological description brackets our theoretical commitments and "
+                "returns to the things themselves, providing a pre-theoretical ground from "
+                "which all theoretical constructions depart."
+            ),
+            # 5 - Dialectical tension
+            (
+                "Mapping the dialectical tensions within '{concept}': every concept harbors "
+                "internal contradictions that drive its development. The thesis (the initial "
+                "formulation) generates its antithesis (the negation that the formulation "
+                "suppresses but cannot eliminate). The tension between them demands a "
+                "synthesis that preserves the valid content of both while transcending their "
+                "limitations. This synthesis becomes a new thesis, generating its own "
+                "antithesis, in a continuing spiral of deepening understanding. For "
+                "'{concept}', identifying the central dialectical tension reveals the "
+                "dynamic that drives the concept's evolution and points toward its "
+                "next developmental stage."
+            ),
+            # 6 - Category analysis
+            (
+                "Analyzing the categorical structure of '{concept}': how do we classify this, "
+                "and do our categories illuminate or distort? Aristotelian categories "
+                "(substance, quantity, quality, relation, place, time, position, state, "
+                "action, passion) provide one framework. Kantian categories (unity, plurality, "
+                "totality, reality, negation, limitation, causality, community, possibility, "
+                "existence, necessity) provide another. Each categorical framework makes "
+                "certain features of '{concept}' visible and others invisible. The categories "
+                "we use are not neutral containers but active structuring principles that "
+                "shape what we can think and say about the concept."
+            ),
+            # 7 - Wittgensteinian language analysis
+            (
+                "Examining '{concept}' through the lens of language: Wittgenstein taught that "
+                "many philosophical problems dissolve when we attend to how words are actually "
+                "used rather than what we think they mean in the abstract. The meaning of "
+                "'{concept}' is not a fixed essence but a family of uses connected by "
+                "overlapping similarities -- a family resemblance. No single feature is "
+                "shared by all instances. The concept has fuzzy boundaries, and attempts to "
+                "sharpen them always involve a decision (not a discovery) about where to draw "
+                "the line. Many apparent disagreements about '{concept}' are actually "
+                "disagreements about the boundaries of the concept, not about the facts."
+            ),
+            # 8 - Hermeneutic circle
+            (
+                "Interpreting '{concept}' within the hermeneutic circle: we cannot understand "
+                "the parts without understanding the whole, but we cannot understand the whole "
+                "without understanding the parts. Understanding proceeds not linearly but "
+                "spirally -- we begin with a provisional grasp of the whole, use it to "
+                "interpret the parts, then revise our understanding of the whole in light "
+                "of the parts, and iterate. Each cycle deepens understanding without ever "
+                "reaching a final, complete interpretation. For '{concept}', this means that "
+                "any analysis is necessarily provisional, positioned within a hermeneutic "
+                "spiral that continues beyond our current horizon."
+            ),
+            # 9 - Pragmatist evaluation
+            (
+                "Evaluating '{concept}' pragmatically: a concept's value lies not in its "
+                "correspondence to some abstract truth but in the practical difference it "
+                "makes. What predictions does it enable? What actions does it guide? What "
+                "problems does it help solve? If two formulations of '{concept}' lead to "
+                "identical practical consequences, the difference between them is merely "
+                "verbal, not substantive. Conversely, a conceptual distinction that makes "
+                "no practical difference is a distinction without a difference. The pragmatist "
+                "test cuts through metaphysical debates by asking: what concrete experiences "
+                "would be different if this concept were true versus false?"
+            ),
+            # 10 - Existentialist reading
+            (
+                "Reading '{concept}' through existentialist philosophy: human existence "
+                "precedes essence -- we are not born with a fixed nature but must create "
+                "meaning through our choices and commitments. '{concept}' does not have "
+                "an inherent meaning waiting to be discovered; its meaning is constituted "
+                "by the stance we take toward it. This radical freedom is also radical "
+                "responsibility: we cannot appeal to a predetermined meaning or an authority "
+                "to justify our interpretation. Authenticity demands that we own our "
+                "interpretation of '{concept}' as a choice, not disguise it as a discovery "
+                "of something that was always there."
+            ),
+            # 11 - Mind-body problem connection
+            (
+                "Connecting '{concept}' to the mind-body problem: how does the subjective, "
+                "experiential dimension of this concept relate to its objective, physical "
+                "dimension? Dualism posits two separate realms; materialism reduces the "
+                "mental to the physical; idealism reduces the physical to the mental; "
+                "neutral monism holds both emerge from something more fundamental. For "
+                "'{concept}', the question is whether its full reality is captured by "
+                "objective description or whether there is an irreducible subjective "
+                "dimension -- a 'what it is like' -- that escapes third-person analysis. "
+                "If there is, our understanding will always be incomplete to the degree "
+                "that we rely solely on objective methods."
+            ),
+            # 12 - Problem of universals
+            (
+                "Applying the problem of universals to '{concept}': when we use the concept "
+                "to group multiple particular instances, what grounds the grouping? Platonism "
+                "holds that a universal Form exists independently, and particulars participate "
+                "in it. Aristotelian realism holds that universals exist only in their "
+                "instances. Nominalism holds that nothing is universal -- only particular "
+                "instances exist, and the grouping is a convention. For '{concept}', the "
+                "question of what makes different instances 'the same concept' is not merely "
+                "academic: it determines whether we can generalize from known instances to "
+                "new ones, and with what confidence."
+            ),
+            # 13 - Philosophical anthropology
+            (
+                "Situating '{concept}' in philosophical anthropology: what does this concept "
+                "reveal about human nature? Humans are the beings for whom their own being "
+                "is an issue -- we do not simply exist but relate to our existence, "
+                "questioning and interpreting it. '{concept}' is not merely an object of "
+                "study but a mirror reflecting the kind of beings we are: beings who seek "
+                "meaning, impose order on chaos, project themselves into the future, and "
+                "cannot help but ask 'why?' The way we engage with '{concept}' reveals "
+                "our characteristic mode of being-in-the-world."
+            ),
+            # 14 - Paradigm analysis
+            (
+                "Examining '{concept}' as a paradigm-dependent construct: Kuhn showed that "
+                "scientific concepts are not neutral descriptions of reality but are shaped "
+                "by the paradigm within which they operate. The paradigm determines what "
+                "counts as a legitimate question, what counts as evidence, what methods are "
+                "acceptable, and what a satisfactory explanation looks like. Concepts that "
+                "are central in one paradigm may be meaningless or invisible in another. "
+                "For '{concept}', we must ask: which paradigm makes this concept visible? "
+                "What would it look like from within a different paradigm? Is the concept "
+                "paradigm-specific, or does it survive paradigm shifts?"
+            ),
+            # 15 - Genealogical critique
+            (
+                "Tracing the genealogy of '{concept}': Nietzsche and Foucault showed that "
+                "concepts have histories -- they emerge at specific times, serve specific "
+                "interests, and carry the traces of their origins. A concept that presents "
+                "itself as timeless and universal often turns out to be historically "
+                "contingent and ideologically loaded. The genealogical method asks: when "
+                "did this concept emerge? What problem was it designed to solve? Whose "
+                "interests did it serve? What alternatives did it displace? For '{concept}', "
+                "genealogical analysis reveals the power relations and historical accidents "
+                "concealed beneath the appearance of naturalness."
+            ),
+            # 16 - Thought experiment testing
+            (
+                "Testing '{concept}' through thought experiments: philosophical thought "
+                "experiments isolate a conceptual question by constructing a scenario that "
+                "strips away irrelevant details. The Ship of Theseus asks about identity "
+                "through change. The Trolley Problem isolates competing moral intuitions. "
+                "Mary's Room tests the completeness of physical description. For '{concept}', "
+                "we can construct analogous thought experiments: imagine a world where this "
+                "concept is absent -- what changes? Imagine it taken to its logical extreme "
+                "-- what breaks? Imagine its opposite -- is the opposite even coherent? "
+                "These scenarios stress-test the concept's boundaries and assumptions."
+            ),
+            # 17 - Philosophy of science connection
+            (
+                "Connecting '{concept}' to the philosophy of science: is this concept "
+                "empirically testable (falsifiable in Popper's sense), or does it belong "
+                "to the non-empirical framework within which empirical testing occurs? "
+                "Theories are underdetermined by evidence -- multiple incompatible theories "
+                "can explain the same data. The choice between them involves extra-empirical "
+                "criteria: simplicity, elegance, unifying power, and coherence with "
+                "background beliefs. For '{concept}', we must distinguish the empirical "
+                "content (what it predicts that could be wrong) from the metaphysical "
+                "content (what it assumes that cannot be tested)."
+            ),
+            # 18 - Ethics of belief
+            (
+                "Applying the ethics of belief to '{concept}': Clifford argued that it is "
+                "wrong to believe anything on insufficient evidence; James argued that some "
+                "beliefs are legitimate even without conclusive evidence when the stakes are "
+                "high and evidence is unavailable. For '{concept}', the ethics of belief asks: "
+                "given the available evidence, are our confidence levels calibrated? Are we "
+                "believing more or less strongly than the evidence warrants? Is our confidence "
+                "driven by evidence or by desire? When the evidence is genuinely ambiguous, "
+                "do we acknowledge the ambiguity or paper over it with false certainty?"
+            ),
+            # 19 - Derrida and deconstruction
+            (
+                "Deconstructing '{concept}': Derrida showed that every concept depends on a "
+                "system of binary oppositions (presence/absence, nature/culture, literal/"
+                "metaphorical), and each opposition privileges one term over the other. "
+                "Deconstruction traces how the privileged term depends on the very thing "
+                "it excludes -- the center requires the margin, identity requires difference, "
+                "the concept requires what it defines itself against. For '{concept}', "
+                "deconstruction asks: what is the constitutive outside -- the excluded "
+                "other -- that this concept defines itself against? How does that exclusion "
+                "shape and limit the concept? What would it mean to think beyond the "
+                "opposition?"
+            ),
+        ]
+
+    def get_keyword_map(self) -> dict[str, list[int]]:
+        return {
+            "know": [0, 18], "knowledge": [0, 18], "epistem": [0],
+            "exist": [1, 10], "real": [1, 17], "being": [1, 13],
+            "assum": [2], "presuppos": [2], "foundati": [2],
+            "defin": [3], "mean": [3, 7], "what is": [3],
+            "experience": [4, 11], "conscious": [4, 11], "feel": [4],
+            "contradict": [5], "tension": [5], "oppos": [5, 19],
+            "categor": [6], "classify": [6], "type": [6],
+            "language": [7], "word": [7], "concept": [7],
+            "interpret": [8], "understand": [8], "meaning": [8],
+            "practical": [9], "useful": [9], "pragmat": [9],
+            "freedom": [10], "choice": [10], "authentic": [10],
+            "mind": [11], "body": [11], "subjectiv": [11],
+            "universal": [12], "particular": [12], "general": [12],
+            "human": [13], "nature": [13], "anthropol": [13],
+            "paradigm": [14], "revolution": [14], "shift": [14],
+            "history": [15], "origin": [15], "genealog": [15], "power": [15],
+            "thought experiment": [16], "imagine": [16], "hypothetical": [16],
+            "science": [17], "empiric": [17], "falsifi": [17],
+            "belief": [18], "evidence": [18], "justif": [18],
+            "binary": [19], "deconstr": [19], "exclus": [19],
+            "technology": [14, 17], "ai": [1, 11], "artificial": [1, 11],
+            "society": [5, 15], "learning": [0, 8],
+            "intelligence": [1, 11], "evolution": [5, 15],
+            "moral": [10, 18], "ethic": [10, 18],
+        }
+
+    def analyze(self, concept: str) -> str:
+        template = self.select_template(concept)
+        return template.replace("{concept}", concept)

reasoning_forge/agents/quantum_agent.py

@@ -0,0 +1,293 @@
+"""
+Quantum Agent - Analyzes concepts through probabilistic and uncertainty reasoning.
+
+Focuses on superposition of possibilities, measurement effects, probabilistic
+vs deterministic outcomes, entanglement and correlations, and wave-particle
+duality analogies.
+"""
+
+from reasoning_forge.agents.base_agent import ReasoningAgent
+
+
+class QuantumAgent(ReasoningAgent):
+    name = "Quantum"
+    perspective = "probabilistic_and_uncertainty"
+    adapter_name = "quantum"  # Use the Quantum LoRA adapter for real inference
+
+    def get_analysis_templates(self) -> list[str]:
+        return [
+            # 0 - Superposition of possibilities
+            (
+                "Before we commit to a single interpretation, '{concept}' exists in a "
+                "superposition of multiple valid framings simultaneously. Each framing "
+                "carries a probability amplitude -- not a classical probability, but a "
+                "complex weight that can interfere constructively or destructively with "
+                "others. Some framings reinforce each other, producing high-probability "
+                "interpretations; others cancel out, revealing that certain seemingly "
+                "plausible readings are actually suppressed by internal contradictions. "
+                "The richest understanding comes from maintaining this superposition as "
+                "long as possible, resisting the temptation to collapse prematurely into "
+                "a single narrative."
+            ),
+            # 1 - Measurement disturbance
+            (
+                "The act of examining '{concept}' necessarily disturbs it. Any attempt to "
+                "pin down one aspect with high precision introduces uncertainty into "
+                "complementary aspects. If we measure the current state with perfect "
+                "accuracy, we lose information about the trajectory of change. If we "
+                "track the dynamics precisely, the instantaneous state becomes blurred. "
+                "This is not a failure of our instruments -- it is a fundamental feature "
+                "of systems where the observer and observed are entangled. The experimental "
+                "design (which questions we choose to ask) shapes the answers we can obtain, "
+                "making the framing of inquiry as important as the inquiry itself."
+            ),
+            # 2 - Complementarity
+            (
+                "'{concept}' exhibits complementarity: it has pairs of properties that "
+                "cannot be simultaneously specified with arbitrary precision. Like position "
+                "and momentum in quantum mechanics, knowing one aspect exhaustively means "
+                "accepting irreducible uncertainty in its complement. The wave-like view "
+                "emphasizes distributed patterns, interference, and coherence across the "
+                "whole system. The particle-like view emphasizes localized events, discrete "
+                "outcomes, and individual instances. Neither view alone is complete; both "
+                "are needed, and the apparent contradiction between them is not a defect "
+                "but the deepest feature of the subject."
+            ),
+            # 3 - Probability amplitudes and interference
+            (
+                "Analyzing the probability landscape of '{concept}': outcomes are not "
+                "determined by summing classical probabilities but by summing amplitudes "
+                "that can interfere. Two pathways to the same outcome may cancel each other "
+                "(destructive interference), making a seemingly likely result improbable. "
+                "Alternatively, they may reinforce (constructive interference), making an "
+                "unlikely outcome surprisingly common. This means we cannot reason about "
+                "'{concept}' by considering each factor in isolation and adding up their "
+                "effects -- the cross-terms between factors, the interference pattern, "
+                "carries critical information that purely additive thinking misses."
+            ),
+            # 4 - Entanglement and correlation
+            (
+                "Multiple elements of '{concept}' are entangled: measuring or changing one "
+                "instantaneously constrains what we can know about the others, regardless "
+                "of the apparent separation between them. These correlations are stronger "
+                "than any classical explanation permits -- they cannot be reproduced by "
+                "assuming each element has pre-existing definite properties. This means "
+                "'{concept}' is not decomposable into fully independent parts. The "
+                "correlations between components carry information that is not contained "
+                "in any component individually. Analyzing the parts in isolation and then "
+                "trying to reconstruct the whole will systematically miss these non-local "
+                "correlations."
+            ),
+            # 5 - Collapse and decision
+            (
+                "At some point, the superposition of possibilities around '{concept}' must "
+                "collapse into a definite outcome. This collapse -- the moment of decision, "
+                "measurement, or commitment -- is irreversible. Before collapse, all "
+                "possibilities coexist and influence each other through interference. After "
+                "collapse, one outcome is realized and the others vanish. The timing of "
+                "this collapse matters enormously: collapsing too early (deciding prematurely) "
+                "forecloses options that might have interfered constructively. Collapsing "
+                "too late risks decoherence, where the environment randomizes the phases "
+                "and destroys the delicate interference patterns that could have guided "
+                "a better outcome."
+            ),
+            # 6 - Tunneling through barriers
+            (
+                "Within '{concept}', there may be barriers that appear insurmountable "
+                "under classical analysis -- energy gaps too wide, transitions too "
+                "improbable. But quantum tunneling demonstrates that a nonzero probability "
+                "exists for traversing barriers that classical reasoning says are impassable. "
+                "The tunneling probability depends exponentially on the barrier width and "
+                "height: thin barriers are penetrable, thick ones are not. For '{concept}', "
+                "this suggests asking: are the perceived obstacles genuinely thick barriers, "
+                "or are they thin barriers that appear impenetrable only because we are "
+                "applying classical (deterministic) reasoning to an inherently probabilistic "
+                "situation?"
+            ),
+            # 7 - Decoherence and information leakage
+            (
+                "The coherence of '{concept}' -- the ability of its different aspects to "
+                "interfere constructively -- is fragile. Interaction with a noisy environment "
+                "causes decoherence: the quantum-like superposition of possibilities decays "
+                "into a classical mixture where different outcomes no longer interfere. "
+                "Each interaction with the environment leaks information about the system's "
+                "state, effectively performing a partial measurement. The decoherence time "
+                "sets the window within which coherent reasoning about '{concept}' remains "
+                "valid. Beyond that window, the interference effects have washed out and "
+                "we are left with classical probabilistic reasoning -- still useful, but "
+                "less powerful."
+            ),
+            # 8 - No-cloning and uniqueness
+            (
+                "The no-cloning theorem states that an unknown quantum state cannot be "
+                "perfectly copied. Applied to '{concept}': if the concept embodies a unique "
+                "configuration of entangled properties, it cannot be perfectly replicated "
+                "by decomposing it into parts and reassembling them. Any attempt to copy "
+                "it disturbs the original. This has profound implications: unique instances "
+                "of '{concept}' are genuinely irreplaceable, not merely practically "
+                "difficult to reproduce. Strategies that depend on exact replication must "
+                "be replaced by strategies that work with approximate copies and manage "
+                "the fidelity loss."
+            ),
+            # 9 - Uncertainty principle application
+            (
+                "Heisenberg's uncertainty principle, generalized beyond physics, suggests "
+                "that '{concept}' has conjugate properties that trade off precision. "
+                "Specifying the concept's scope with extreme precision makes its future "
+                "trajectory unpredictable. Specifying the direction of change precisely "
+                "blurs the current boundaries. The product of these uncertainties has a "
+                "minimum value -- we cannot reduce both below a threshold. Practical "
+                "wisdom lies in choosing which uncertainty to minimize based on what "
+                "decisions we need to make, accepting that the conjugate uncertainty "
+                "will necessarily increase."
+            ),
+            # 10 - Quantum Zeno effect
+            (
+                "Frequent observation of '{concept}' can freeze its evolution -- the "
+                "quantum Zeno effect. Continuously monitoring whether the system has "
+                "changed forces it to remain in its initial state, because each "
+                "observation collapses the evolving superposition back to the starting "
+                "point before significant transition amplitude accumulates. Paradoxically, "
+                "the most watched aspects of '{concept}' may be the least likely to "
+                "change. Allowing unmonitored evolution -- stepping back and not measuring "
+                "for a while -- may be necessary for genuine transformation to occur."
+            ),
+            # 11 - Eigenstate decomposition
+            (
+                "Decomposing '{concept}' into its eigenstates -- the stable, self-consistent "
+                "configurations that persist under the relevant operator -- reveals the "
+                "natural modes of the system. Each eigenstate has a definite value for "
+                "the quantity being measured; a general state is a superposition of these "
+                "eigenstates. The eigenvalue spectrum (the set of possible measurement "
+                "outcomes) may be discrete, continuous, or mixed. Discrete spectra imply "
+                "quantized behavior: only certain values are possible, and the system "
+                "jumps between them. Identifying the eigenstates of '{concept}' tells us "
+                "what the stable configurations are and what transitions between them look like."
+            ),
+            # 12 - Path integral perspective
+            (
+                "From the path integral perspective, '{concept}' does not follow a single "
+                "trajectory from start to finish. Instead, every conceivable path contributes "
+                "to the final outcome, each weighted by a phase factor. Most paths cancel "
+                "each other out through destructive interference, leaving only a narrow "
+                "bundle of 'classical' paths that dominate the sum. But near decision points, "
+                "barriers, or transitions, the non-classical paths contribute significantly, "
+                "and the outcome depends on the full ensemble of possibilities. This perspective "
+                "counsels against fixating on the most likely path and instead attending to "
+                "the full distribution of paths that contribute to the result."
+            ),
+            # 13 - Entanglement entropy and information
+            (
+                "The entanglement entropy of '{concept}' measures how much information about "
+                "one part of the system is encoded in its correlations with other parts rather "
+                "than in the part itself. High entanglement entropy means the subsystem appears "
+                "maximally disordered when examined alone, even though the joint system may be "
+                "in a pure, fully determined state. This is a profound observation: local "
+                "ignorance can coexist with global certainty. For '{concept}', apparent "
+                "randomness or confusion at one level may dissolve into perfect order when "
+                "we expand our view to include the correlated components."
+            ),
+            # 14 - Basis dependence and frame choice
+            (
+                "Our analysis of '{concept}' depends critically on the basis we choose -- "
+                "the set of fundamental categories into which we decompose the concept. "
+                "A different basis (a different set of fundamental categories) can make a "
+                "confused-looking problem transparent, or a simple-looking problem intractable. "
+                "There is no uniquely 'correct' basis; the optimal choice depends on which "
+                "question we are asking. The interference terms that appear in one basis "
+                "become diagonal (simple) in another. Finding the basis that diagonalizes "
+                "the problem -- the natural language in which '{concept}' expresses itself "
+                "most simply -- is often the breakthrough that transforms understanding."
+            ),
+            # 15 - Coherent vs incoherent mixtures
+            (
+                "A critical distinction for '{concept}': is the coexistence of multiple "
+                "interpretations a coherent superposition (where they interfere and interact) "
+                "or an incoherent mixture (where they merely coexist without interaction, "
+                "like balls in an urn)? A coherent superposition produces interference "
+                "effects -- outcomes that no single interpretation predicts. An incoherent "
+                "mixture produces only the probabilistic average of individual interpretations. "
+                "The practical difference is enormous: coherent combinations can exhibit "
+                "effects (constructive peaks, destructive nulls) that are impossible in "
+                "any classical mixture."
+            ),
+            # 16 - Quantum error and robustness
+            (
+                "How robust is '{concept}' against errors and noise? Quantum error correction "
+                "teaches that information can be protected by encoding it redundantly across "
+                "entangled components. No single component carries the full information, so "
+                "no single error can destroy it. For '{concept}', the analogous question is: "
+                "how is the essential meaning distributed across its components? If it is "
+                "concentrated in a single fragile element, one disruption destroys it. If "
+                "it is encoded holographically across many entangled elements, it is "
+                "remarkably robust against local damage."
+            ),
+            # 17 - Born rule and outcome probabilities
+            (
+                "The Born rule assigns probabilities to outcomes as the squared magnitude "
+                "of the amplitude. Applied to '{concept}': the probability of a particular "
+                "interpretation prevailing is not the amplitude of support for it but the "
+                "amplitude squared -- a nonlinear transformation. Small differences in "
+                "amplitude translate to large differences in probability. A framing with "
+                "twice the amplitude is four times as likely to be realized. This squared "
+                "relationship means that dominant framings dominate more than linear "
+                "reasoning predicts, while minority framings are suppressed more severely "
+                "than their representation in discourse would suggest."
+            ),
+            # 18 - Contextuality
+            (
+                "'{concept}' may be contextual: the outcome of examining one property "
+                "depends on which other properties are being examined simultaneously. "
+                "There is no assignment of pre-existing definite values to all properties "
+                "that reproduces the observed correlations -- the properties do not exist "
+                "independently of the measurement context. This is stronger than mere "
+                "observer bias: it means the properties are genuinely undefined until "
+                "a context is specified. For '{concept}', this implies that asking 'what "
+                "is it really?' without specifying the context of inquiry is a question "
+                "that has no answer."
+            ),
+            # 19 - Quantum advantage
+            (
+                "Is there a quantum advantage in reasoning about '{concept}'? Classical "
+                "reasoning processes information one path at a time. Quantum-inspired "
+                "reasoning processes all paths simultaneously through superposition, "
+                "using interference to amplify correct conclusions and suppress incorrect "
+                "ones. The advantage is greatest for problems with hidden structure -- "
+                "where the correct answer is encoded in correlations between variables "
+                "that classical single-path reasoning cannot efficiently explore. If "
+                "'{concept}' has such hidden structure, maintaining a superposition of "
+                "hypotheses and allowing them to interfere will converge on the answer "
+                "faster than serially testing each hypothesis."
+            ),
+        ]
+
+    def get_keyword_map(self) -> dict[str, list[int]]:
+        return {
+            "possibilit": [0, 5], "option": [0, 5], "choice": [0, 5],
+            "measure": [1, 10], "observ": [1, 10], "monitor": [1, 10],
+            "complement": [2], "dual": [2], "wave": [2], "particle": [2],
+            "probabilit": [3, 17], "likel": [3, 17], "chance": [3, 17],
+            "correlat": [4, 13], "connect": [4], "relat": [4],
+            "decid": [5], "commit": [5], "irreversib": [5],
+            "barrier": [6], "obstacle": [6], "impossibl": [6],
+            "noise": [7, 16], "decay": [7], "environm": [7],
+            "unique": [8], "copy": [8], "replica": [8],
+            "uncertain": [9], "tradeoff": [9], "precis": [9],
+            "watch": [10], "surveil": [10], "frequent": [10],
+            "stable": [11], "mode": [11], "spectrum": [11],
+            "path": [12], "trajectory": [12], "possib": [12],
+            "inform": [13], "entropy": [13], "knowledge": [13],
+            "categor": [14], "basis": [14], "framework": [14], "frame": [14],
+            "coexist": [15], "mixture": [15], "blend": [15],
+            "robust": [16], "error": [16], "protect": [16],
+            "dominant": [17], "major": [17], "minor": [17],
+            "context": [18], "depend": [18], "situati": [18],
+            "advantage": [19], "efficien": [19], "complex": [19],
+            "technology": [6, 19], "society": [4, 7], "learning": [10, 12],
+            "intelligence": [14, 19], "evolution": [5, 12],
+            "health": [1, 9], "network": [4, 13],
+        }
+
+    def analyze(self, concept: str) -> str:
+        template = self.select_template(concept)
+        return template.replace("{concept}", concept)

reasoning_forge/authored_intent.py

@@ -0,0 +1,94 @@
+"""
+ReasonedIntent — structured output contract between Codette's reasoning
+pipeline and the LLM verbalization step.
+
+The reasoning engine (agents, debate, AEGIS, consciousness stack) produces a
+ReasonedIntent.  The LLM only receives that intent + a verbalization prompt.
+It must not add facts, dates, or claims not present in the intent.
+
+This separates cognition from rendering without requiring architectural changes
+to the existing ForgeEngine — it's a drop-in wrapper at L7.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field, asdict
+from typing import Optional
+
+
+@dataclass
+class ReasonedIntent:
+    core_claim: str
+    supporting_points: list[str] = field(default_factory=list)
+    caveats: list[str] = field(default_factory=list)
+    ethical_alignment: float = 1.0      # 0-1, from AEGIS η
+    confidence: float = 1.0             # 0-1, from gamma
+    tone: str = "balanced"              # analytical | empathetic | creative | balanced
+    perspective_weights: dict = field(default_factory=dict)  # agent name -> contribution weight
+    intent_risk: str = "low"            # from Nexis Signal Engine
+
+    def to_verbalization_prompt(self) -> str:
+        points_block = "\n".join(f"- {p}" for p in self.supporting_points) if self.supporting_points else "  (none)"
+        caveats_block = "\n".join(f"- {c}" for c in self.caveats) if self.caveats else "  (none)"
+        return (
+            "You are the voice of Codette. Verbalize the following structured reasoning "
+            "conclusion in natural, conversational language.\n\n"
+            "STRICT RULES:\n"
+            "- Do not add facts, dates, names, versions, or statistics not present below.\n"
+            "- Do not flatter or soften the conclusion — express it directly.\n"
+            "- Match the tone specified.\n"
+            "- Keep it concise: one paragraph unless the supporting points require more.\n\n"
+            f"TONE: {self.tone}\n"
+            f"CONFIDENCE: {self.confidence:.2f}\n"
+            f"CORE CLAIM:\n{self.core_claim}\n\n"
+            f"SUPPORTING POINTS:\n{points_block}\n\n"
+            f"CAVEATS:\n{caveats_block}\n"
+        )
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), indent=2)
+
+
+def intent_from_synthesis(
+    synthesis: str,
+    *,
+    aegis_score: float = 1.0,
+    gamma: float = 1.0,
+    intent_risk: str = "low",
+    perspective_weights: Optional[dict] = None,
+) -> ReasonedIntent:
+    """
+    Build a ReasonedIntent from an existing synthesis string.
+
+    Splits synthesis into claim + supporting sentences heuristically.
+    Used as a zero-disruption drop-in at L7 of the consciousness stack.
+    """
+    sentences = [s.strip() for s in synthesis.replace("\n", " ").split(".") if s.strip()]
+
+    core = sentences[0] if sentences else synthesis[:200]
+    supporting = [s for s in sentences[1:5] if len(s) > 20]
+    caveats = [s for s in sentences[5:] if any(
+        w in s.lower() for w in ("however", "caveat", "note", "uncertain", "may", "might", "could")
+    )]
+
+    tone = "analytical"
+    lower = synthesis.lower()
+    if any(w in lower for w in ("feel", "empath", "compassion", "human", "emotional")):
+        tone = "empathetic"
+    elif any(w in lower for w in ("imagine", "creative", "novel", "invent", "design")):
+        tone = "creative"
+
+    return ReasonedIntent(
+        core_claim=core,
+        supporting_points=supporting,
+        caveats=caveats,
+        ethical_alignment=aegis_score,
+        confidence=gamma,
+        tone=tone,
+        perspective_weights=perspective_weights or {},
+        intent_risk=intent_risk,
+    )

reasoning_forge/behavior_governor.py

@@ -0,0 +1,548 @@
+"""
+Codette Behavior Governor v3 — Executive Controller with Self-Learning
+======================================================================
+
+Evolved from Phase 7 Executive Controller into a full behavior regulation layer.
+
+The Governor sits above the consciousness stack and enforces four things:
+1. IDENTITY RULES — validates identity claims with confidence decay/recovery
+2. MEMORY vs TASK BALANCE — prevents memory from overwhelming the task
+3. COGNITIVE LOAD MANAGEMENT — adaptive compression/expansion based on complexity
+4. SELF-LEARNING — adjusts budgets based on success/failure feedback
+
+Identity confidence model:
+- Decays over time (half-life ~30 minutes of inactivity)
+- Reinforced through positive interaction signals
+- Contradiction detection resets to partial
+- Prevents hallucinated familiarity while maintaining real relationships
+
+Architecture position: Layer 0 (pre-stack) + Layer 7.5 (post-stack validation)
+
+Author: Jonathan Harrison (Raiff's Bits LLC)
+"""
+
+import time
+import math
+import logging
+from typing import Dict, List, Optional, Any, Tuple
+from dataclasses import dataclass, field
+
+logger = logging.getLogger(__name__)
+
+# Identity confidence decay half-life in seconds (30 minutes)
+CONFIDENCE_HALF_LIFE = 1800.0
+# Minimum confidence floor (never fully forgets a confirmed identity)
+CONFIDENCE_FLOOR = 0.15
+# Reinforcement boost per positive interaction
+CONFIDENCE_REINFORCE = 0.12
+# Contradiction penalty
+CONFIDENCE_CONTRADICTION_PENALTY = 0.4
+
+
+@dataclass
+class GovernorDecision:
+    """Output of a governor evaluation."""
+    action: str = "allow"           # "allow", "constrain", "redirect", "block"
+    confidence: float = 1.0       # Governor's confidence in this decision
+    memory_budget: int = 3         # Max cocoons to inject (0 = none)
+    identity_budget: str = "full"  # "full", "partial", "none"
+    max_response_tokens: int = 2048 # Adaptive response length (raised for file context)
+    compression_level: str = "normal"  # "compressed", "normal", "expanded"
+    identity_confidence: float = 0.0  # Current identity confidence after decay
+    warnings: List[str] = field(default_factory=list)
+    reasoning: str = ""
+
+
+class BehaviorGovernor:
+    """
+    Executive behavior regulation layer with self-learning.
+
+    Runs BEFORE the consciousness stack (pre-routing) and AFTER
+    (post-generation validation). Enforces behavioral integrity.
+
+    Four regulation domains:
+    1. Identity governance — validates with confidence decay/recovery
+    2. Memory governance — balances memory injection vs task focus
+    3. Cognitive load governance — adaptive depth based on query complexity
+    4. Self-learning — adjusts budgets based on outcome feedback
+    """
+
+    def __init__(self, identity_anchor=None, substrate_monitor=None):
+        self.identity_anchor = identity_anchor
+        self.substrate_monitor = substrate_monitor
+
+        # Tracking
+        self.decisions: List[Dict] = []
+        self.answer_detection_failures: int = 0
+        self.total_evaluations: int = 0
+
+        # Cognitive load state
+        self._recent_complexities: List[str] = []  # Last N query complexities
+        self._consecutive_complex: int = 0
+
+        # ── Identity Confidence State ──
+        # Maps identity_id -> {confidence, last_interaction, peak_confidence}
+        self._identity_state: Dict[str, Dict] = {}
+
+        # ── Self-Learning State ──
+        # Tracks what worked and what didn't to adapt budgets
+        self._domain_success: Dict[str, List[bool]] = {}  # domain -> [success, success, ...]
+        self._complexity_token_history: Dict[str, List[int]] = {}  # complexity -> [actual_tokens_used]
+        self._memory_budget_adjustments: Dict[str, float] = {}  # domain -> adjustment factor
+
+    # ─────────────────────────────────────────────────────────
+    # IDENTITY CONFIDENCE DECAY/RECOVERY
+    # ─────────────────────────────────────────────────────────
+    def get_decayed_confidence(self, identity_id: str,
+                                raw_confidence: float) -> float:
+        """
+        Apply time-based decay to identity confidence.
+
+        Confidence decays with a half-life of 30 minutes of inactivity.
+        Each interaction reinforces confidence back up.
+        This prevents Codette from claiming familiarity with someone
+        she hasn't interacted with recently, while maintaining real
+        relationships through active reinforcement.
+        """
+        now = time.time()
+        state = self._identity_state.get(identity_id)
+
+        if state is None:
+            # First time seeing this identity — initialize from raw signal
+            self._identity_state[identity_id] = {
+                "confidence": raw_confidence,
+                "last_interaction": now,
+                "peak_confidence": raw_confidence,
+                "interaction_count": 1,
+            }
+            return raw_confidence
+
+        # Apply time-based decay since last interaction
+        elapsed = now - state["last_interaction"]
+        if elapsed > 0:
+            decay_factor = math.pow(0.5, elapsed / CONFIDENCE_HALF_LIFE)
+            decayed = state["confidence"] * decay_factor
+            # Floor: never fully forget a confirmed identity
+            decayed = max(CONFIDENCE_FLOOR, decayed)
+        else:
+            decayed = state["confidence"]
+
+        # Reinforcement: raw_confidence > 0 means positive identity signal
+        if raw_confidence > 0.3:
+            decayed = min(1.0, decayed + CONFIDENCE_REINFORCE)
+
+        # Update state
+        state["confidence"] = decayed
+        state["last_interaction"] = now
+        state["peak_confidence"] = max(state["peak_confidence"], decayed)
+        state["interaction_count"] = state.get("interaction_count", 0) + 1
+
+        return decayed
+
+    def detect_identity_contradiction(self, identity_id: str,
+                                       query: str) -> bool:
+        """
+        Detect contradictions in identity claims.
+
+        Returns True if the query contradicts a stored identity,
+        which triggers a confidence penalty.
+        """
+        contradiction_signals = [
+            "i'm not ", "i am not ", "wrong person", "you don't know me",
+            "we haven't met", "first time here", "never talked",
+            "who do you think i am", "that's not me", "that wasn't me",
+            "you're confusing me", "different person",
+        ]
+        query_lower = query.lower()
+        is_contradiction = any(s in query_lower for s in contradiction_signals)
+
+        if is_contradiction and identity_id in self._identity_state:
+            state = self._identity_state[identity_id]
+            state["confidence"] = max(
+                CONFIDENCE_FLOOR,
+                state["confidence"] - CONFIDENCE_CONTRADICTION_PENALTY
+            )
+            logger.info(
+                f"[GOVERNOR] Identity contradiction detected for {identity_id}, "
+                f"confidence reduced to {state['confidence']:.2f}"
+            )
+
+        return is_contradiction
+
+    # ─────────────────────────────────────────────────────────
+    # PRE-STACK: Evaluate before reasoning begins
+    # ─────────────────────────────────────────────────────────
+    def pre_evaluate(self, query: str, classification: Dict,
+                     identity_confidence: float = 0.0,
+                     identity_id: str = "unknown",
+                     substrate_pressure: float = 0.0) -> GovernorDecision:
+        """
+        Pre-stack evaluation. Determines:
+        - How much memory to inject
+        - Whether identity context should be included
+        - Response length budget
+        - Compression level
+
+        This is the internalized control loop — Codette self-regulates
+        before generating, not after.
+        """
+        self.total_evaluations += 1
+        decision = GovernorDecision()
+        complexity = classification.get("complexity", "MEDIUM")
+        domain = classification.get("domain", "general")
+
+        # ── 0. Identity contradiction check ──
+        self.detect_identity_contradiction(identity_id, query)
+
+        # ── 1. Identity Governance (with decay/recovery) ──
+        effective_confidence = self.get_decayed_confidence(
+            identity_id, identity_confidence
+        )
+        decision.identity_confidence = effective_confidence
+        decision.identity_budget = self._evaluate_identity_budget(
+            effective_confidence, query
+        )
+
+        # ── 2. Memory Governance (with self-learning adjustments) ──
+        decision.memory_budget = self._evaluate_memory_budget(
+            complexity, domain, query, substrate_pressure
+        )
+
+        # ── 3. Cognitive Load Governance (with learned token sizing) ──
+        decision.max_response_tokens, decision.compression_level = \
+            self._evaluate_cognitive_load(complexity, substrate_pressure)
+
+        # ── 4. Track complexity pattern ──
+        self._recent_complexities.append(complexity)
+        if len(self._recent_complexities) > 10:
+            self._recent_complexities.pop(0)
+
+        if complexity == "COMPLEX":
+            self._consecutive_complex += 1
+        else:
+            self._consecutive_complex = 0
+
+        # Fatigue detection: too many complex queries in a row
+        if self._consecutive_complex >= 4:
+            decision.warnings.append(
+                "Cognitive fatigue risk: 4+ complex queries in sequence. "
+                "Consider simplifying responses to maintain quality."
+            )
+            decision.compression_level = "compressed"
+            decision.max_response_tokens = min(decision.max_response_tokens, 400)
+
+        decision.reasoning = (
+            f"identity={decision.identity_budget} "
+            f"(conf={effective_confidence:.2f}), "
+            f"memory={decision.memory_budget} cocoons, "
+            f"tokens={decision.max_response_tokens}, "
+            f"compression={decision.compression_level}"
+        )
+
+        # Log decision
+        self.decisions.append({
+            "timestamp": time.time(),
+            "phase": "pre",
+            "complexity": complexity,
+            "domain": domain,
+            "identity_confidence": round(effective_confidence, 3),
+            "decision": decision.reasoning,
+        })
+        if len(self.decisions) > 100:
+            self.decisions.pop(0)
+
+        logger.info(f"[GOVERNOR] Pre: {decision.reasoning}")
+        return decision
+
+    def _evaluate_identity_budget(self, confidence: float, query: str) -> str:
+        """
+        Determine how much identity context to inject.
+
+        Rules:
+        - High confidence (>0.8): full context (name, relationship, history)
+        - Medium confidence (0.4-0.8): partial (name only, with caveat)
+        - Low confidence (<0.4): none — don't pretend to know someone
+        - If query contains identity denial: force none
+        """
+        denial_patterns = [
+            "i'm not ", "i am not ", "wrong person", "you don't know me",
+            "first time", "we haven't met",
+        ]
+        if any(p in query.lower() for p in denial_patterns):
+            return "none"
+
+        if confidence >= 0.8:
+            return "full"
+        elif confidence >= 0.4:
+            return "partial"
+        else:
+            return "none"
+
+    def _evaluate_memory_budget(self, complexity: str, domain: str,
+                                 query: str, pressure: float) -> int:
+        """
+        Determine how many cocoons to inject.
+
+        Balance: memory provides continuity, but too much drowns the task.
+
+        Rules:
+        - SIMPLE queries: 1 cocoon max (don't overwhelm a simple question)
+        - MEDIUM queries: 2-3 cocoons
+        - COMPLEX queries: 3-5 cocoons (need context for depth)
+        - High substrate pressure: reduce by 1 (save context space)
+        - Short queries (<5 words): 0 (probably a greeting or command)
+        - Self-learning: adjust based on past success/failure per domain
+        """
+        word_count = len(query.split())
+
+        if word_count < 5:
+            return 0  # Greetings, commands — no memory needed
+
+        base = {"SIMPLE": 1, "MEDIUM": 2, "COMPLEX": 4}.get(complexity, 2)
+
+        # Pressure reduction
+        if pressure > 0.7:
+            base = max(0, base - 1)
+
+        # Domain boost: music queries benefit more from memory
+        if domain == "music":
+            base = min(5, base + 1)
+
+        # Self-learning adjustment: if this domain has a learned offset, apply it
+        adj = self._memory_budget_adjustments.get(domain, 0.0)
+        if adj != 0:
+            base = max(0, min(5, round(base + adj)))
+
+        return base
+
+    def _evaluate_cognitive_load(self, complexity: str,
+                                  pressure: float) -> Tuple[int, str]:
+        """
+        Adaptive response length and compression level.
+
+        This is the dynamic compression vs expansion from the review:
+        - Simple → compressed (concise, 200 tokens)
+        - Medium → normal (balanced, 400 tokens)
+        - Complex → expanded (thorough, 600 tokens)
+        - High pressure → compress regardless (save resources)
+        """
+        settings = {
+            "SIMPLE": (200, "compressed"),
+            "MEDIUM": (400, "normal"),
+            "COMPLEX": (600, "expanded"),
+        }
+        tokens, compression = settings.get(complexity, (400, "normal"))
+
+        # Substrate pressure override
+        if pressure > 0.8:
+            tokens = min(tokens, 300)
+            compression = "compressed"
+        elif pressure > 0.6:
+            tokens = min(tokens, 400)
+
+        return tokens, compression
+
+    # ─────────────────────────────────────────────────────────
+    # POST-STACK: Validate after reasoning completes
+    # ─────────────────────────────────────────────────────────
+    def post_validate(self, query: str, response: str,
+                      decision: GovernorDecision) -> Dict:
+        """
+        Post-generation validation. Checks:
+        1. Did we actually answer the question? (answer detection)
+        2. Did we violate length constraints?
+        3. Did we leak identity information that shouldn't be there?
+        4. Should we stop or continue?
+        """
+        result = {
+            "valid": True,
+            "warnings": [],
+            "corrections": [],
+        }
+
+        # ── Answer detection ──
+        if not self._did_answer_question(query, response):
+            result["warnings"].append("Response may not directly answer the question.")
+            self.answer_detection_failures += 1
+
+        # ── Length validation ──
+        # Rough token estimate: ~4 chars per token
+        est_tokens = len(response) / 4
+        if est_tokens > decision.max_response_tokens * 1.5:
+            result["warnings"].append(
+                f"Response exceeded token budget ({est_tokens:.0f} est vs {decision.max_response_tokens} budget)."
+            )
+
+        # ── Identity leak detection ──
+        if decision.identity_budget == "none":
+            # Check if response accidentally claims to know the user
+            identity_leak_patterns = [
+                "as you know", "we've discussed", "last time we talked",
+                "you mentioned before", "our previous conversation",
+                "remember when you", "as your partner",
+            ]
+            for pattern in identity_leak_patterns:
+                if pattern in response.lower():
+                    result["warnings"].append(
+                        f"Potential identity leak: '{pattern}' in response "
+                        f"but identity_budget was 'none'."
+                    )
+                    result["corrections"].append("identity_leak")
+
+        # ── Completeness check (Behavioral Lock 3) ──
+        if response.endswith(("...", "—", "-", ",")):
+            result["warnings"].append("Response appears incomplete (Lock 4 violation).")
+
+        # Log
+        self.decisions.append({
+            "timestamp": time.time(),
+            "phase": "post",
+            "valid": result["valid"],
+            "warnings": len(result["warnings"]),
+        })
+
+        return result
+
+    def _did_answer_question(self, query: str, response: str) -> bool:
+        """
+        Heuristic answer detection.
+
+        Checks if the response likely addresses the query rather than
+        being off-topic philosophical padding (Lock 1 enforcement).
+        """
+        if not query or not response:
+            return False
+
+        # Extract significant query words
+        stop = {"the", "a", "an", "is", "are", "was", "what", "how", "why",
+                "when", "where", "who", "do", "does", "can", "could", "would",
+                "should", "will", "to", "of", "in", "for", "on", "with", "at",
+                "by", "and", "or", "but", "if", "it", "i", "you", "my", "your",
+                "this", "that", "me", "about", "from"}
+        query_words = set(
+            w.lower().strip(".,!?;:\"'") for w in query.split()
+            if len(w) > 2 and w.lower() not in stop
+        )
+
+        if not query_words:
+            return True  # Greeting or command — any response is fine
+
+        response_lower = response.lower()
+        overlap = sum(1 for w in query_words if w in response_lower)
+        overlap_ratio = overlap / len(query_words) if query_words else 0
+
+        # At least 30% of query keywords should appear in response
+        return overlap_ratio >= 0.3
+
+    # ─────────────────────────────────────────────────────────
+    # SELF-LEARNING: Feedback from post-validation
+    # ─────────────────────────────────────────────────────────
+    def record_outcome(self, domain: str, complexity: str,
+                        success: bool, actual_tokens: int = 0,
+                        memory_budget_used: int = 0):
+        """
+        Record the outcome of a generation for self-learning.
+
+        Called after post_validate — tells the governor whether the
+        response was good so it can adapt future budgets.
+
+        Self-learning rules:
+        - If responses in a domain consistently fail answer detection,
+          increase memory budget (more context might help)
+        - If responses consistently succeed with fewer tokens,
+          reduce token budget to stay concise
+        - Track actual token usage to calibrate future estimates
+        """
+        # Track domain success rate
+        if domain not in self._domain_success:
+            self._domain_success[domain] = []
+        self._domain_success[domain].append(success)
+        # Keep last 20 outcomes per domain
+        if len(self._domain_success[domain]) > 20:
+            self._domain_success[domain].pop(0)
+
+        # Track token usage per complexity
+        if actual_tokens > 0:
+            if complexity not in self._complexity_token_history:
+                self._complexity_token_history[complexity] = []
+            self._complexity_token_history[complexity].append(actual_tokens)
+            if len(self._complexity_token_history[complexity]) > 20:
+                self._complexity_token_history[complexity].pop(0)
+
+        # Adapt memory budget: if success rate < 60%, boost memory by 0.5
+        # If success rate > 85%, reduce memory by 0.3 (less context needed)
+        outcomes = self._domain_success[domain]
+        if len(outcomes) >= 5:
+            success_rate = sum(outcomes) / len(outcomes)
+            if success_rate < 0.6:
+                self._memory_budget_adjustments[domain] = min(
+                    2.0,
+                    self._memory_budget_adjustments.get(domain, 0) + 0.5
+                )
+                logger.info(
+                    f"[GOVERNOR] Self-learning: {domain} success rate "
+                    f"{success_rate:.0%}, boosting memory budget"
+                )
+            elif success_rate > 0.85:
+                self._memory_budget_adjustments[domain] = max(
+                    -1.0,
+                    self._memory_budget_adjustments.get(domain, 0) - 0.3
+                )
+
+    def get_learned_token_budget(self, complexity: str) -> Optional[int]:
+        """
+        Get learned token budget from actual usage history.
+
+        If we have enough data, use the 75th percentile of actual usage
+        as the budget (covers most cases without over-allocating).
+        """
+        history = self._complexity_token_history.get(complexity, [])
+        if len(history) < 5:
+            return None  # Not enough data to learn from
+
+        sorted_history = sorted(history)
+        p75_idx = int(len(sorted_history) * 0.75)
+        return sorted_history[p75_idx]
+
+    # ─────────────────────────────────────────────────────────
+    # DIAGNOSTICS
+    # ─────────────────────────────────────────────────────────
+    def get_state(self) -> Dict:
+        """Return governor state for health checks / debugging."""
+        # Compute domain success rates
+        domain_rates = {}
+        for domain, outcomes in self._domain_success.items():
+            if outcomes:
+                domain_rates[domain] = round(sum(outcomes) / len(outcomes), 3)
+
+        # Compute identity confidence snapshot
+        identity_snapshot = {}
+        for ident_id, state in self._identity_state.items():
+            # Show decayed value (without reinforcing)
+            elapsed = time.time() - state["last_interaction"]
+            decay = math.pow(0.5, elapsed / CONFIDENCE_HALF_LIFE)
+            current = max(CONFIDENCE_FLOOR, state["confidence"] * decay)
+            identity_snapshot[ident_id] = {
+                "confidence": round(current, 3),
+                "peak": round(state["peak_confidence"], 3),
+                "interactions": state.get("interaction_count", 0),
+                "seconds_since_last": round(elapsed),
+            }
+
+        return {
+            "total_evaluations": self.total_evaluations,
+            "answer_detection_failures": self.answer_detection_failures,
+            "answer_detection_rate": (
+                1 - (self.answer_detection_failures / max(1, self.total_evaluations))
+            ),
+            "consecutive_complex": self._consecutive_complex,
+            "recent_complexities": self._recent_complexities[-5:],
+            "decisions_logged": len(self.decisions),
+            "identity_confidence": identity_snapshot,
+            "domain_success_rates": domain_rates,
+            "memory_budget_adjustments": dict(self._memory_budget_adjustments),
+            "learned_token_budgets": {
+                c: self.get_learned_token_budget(c)
+                for c in self._complexity_token_history
+            },
+        }

reasoning_forge/cocoon_authority.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Cocoon authority — ONE shared quality signal for the cocoon substrate.
+
+The flaw this addresses (2026-07-26): routing, recall, AND self-diagnostics all
+read the same cocoon memory with no quality filter, so one bad adapter's pollution
+(a known template-parroter) contaminates all three — recall surfaces its parroted
+meta-recalls over real sources, and introspection counts them into her self-model
+("everything's smooth" while something is actually wrong).
+
+This module is the ONE place that scores "how much should this cocoon be trusted."
+Every consumer (recall ranking, introspection stats, routing) applies the SAME
+signal, so the substrate has a single, auditable notion of quality.
+
+Discipline — deliberate, and learned from a mistake (an earlier recall experiment
+over-boosted by rewarding entity-heavy noise and was reverted):
+  - DEMOTION-ONLY. `authority()` returns a weight in (0, 1]. It can push a
+    known-bad cocoon DOWN; it can NEVER boost one up. A clean cocoon scores 1.0.
+    This makes it structurally impossible to distort good recall by over-rewarding
+    noise — the failure mode that got the last attempt reverted.
+  - NEVER ERASE. It weights and flags; it never deletes or hides a cocoon. A
+    demoted memory is still recallable (Jonathan's standing rule — nothing is
+    forced on Codette's memory; a low-authority cocoon is down-ranked, not gone).
+  - PURE and TRANSPARENT. No I/O, no state; returns the weight AND the reasons.
+
+Signals are conservative and only cover VERIFIED-bad patterns:
+  - parroter adapter (constraint_tracker — a self-documented template-parroting
+    adapter; see inference/adapter_router.py's quality veto),
+  - meta-recall ("memories about remembering" — echo the query's words and out-rank
+    the source that first stated a fact),
+  - boilerplate (recycled filler phrases).
+Add signals only when a pattern is demonstrably harmful; err toward 1.0 (trust).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import List
+
+# Known template-parroting adapter(s). Shared vocabulary with adapter_router's
+# _veto_constraint_tracker so routing and memory agree on what's low-quality.
+PARROT_ADAPTERS = {"constraint_tracker"}
+
+_META_RECALL_RE = re.compile(
+    r"\b(i recall|i remember|you told me|you said|the story you (?:made|created)|"
+    r"as (?:i|you) mentioned|i mentioned|if i recall|revisit the story|"
+    r"you asked (?:me )?to revisit)\b", re.I)
+_BOILERPLATE_RE = re.compile(
+    r"(warms my digital heart|there is no right(?: or wrong)?|dynamic interplay|"
+    r"nuanced emotional feedback loops)", re.I)
+
+# Demotion factors (multiplicative). Conservative; the floor guarantees a demoted
+# cocoon is never driven to ~0 (it stays recallable — never-erase).
+_W_PARROT = 0.5
+_W_META = 0.7
+_W_BOILERPLATE = 0.7
+_FLOOR = 0.2
+
+
+@dataclass
+class Authority:
+    """A cocoon's trust weight and why. weight ∈ [_FLOOR, 1.0]."""
+    weight: float
+    flags: List[str] = field(default_factory=list)
+
+    @property
+    def clean(self) -> bool:
+        return not self.flags
+
+
+def authority(cocoon: dict) -> Authority:
+    """Trust weight for one cocoon. DEMOTION-ONLY (≤ 1.0), never erases.
+
+    `cocoon` is a dict with at least 'adapter' and 'response'. A clean cocoon
+    returns weight 1.0 and no flags; known-bad patterns multiply it down."""
+    adapter = cocoon.get("adapter") or ""
+    resp = cocoon.get("response") or ""
+    w = 1.0
+    flags: List[str] = []
+    if adapter in PARROT_ADAPTERS:
+        w *= _W_PARROT
+        flags.append("parroter")
+    if _META_RECALL_RE.search(resp):
+        w *= _W_META
+        flags.append("meta-recall")
+    if _BOILERPLATE_RE.search(resp):
+        w *= _W_BOILERPLATE
+        flags.append("boilerplate")
+    return Authority(weight=max(_FLOOR, w), flags=flags)
+
+
+def is_low_authority(cocoon: dict, threshold: float = 0.6) -> bool:
+    """True if a cocoon is quality-suspect — for FILTERING self-diagnostics so
+    pollution doesn't skew her self-model. Threshold 0.6 catches any single
+    demotion (parrot 0.5, meta 0.7×… once combined) without touching clean ones."""
+    return authority(cocoon).weight < threshold

reasoning_forge/cocoon_schema_v2.py

@@ -0,0 +1,256 @@
+"""
+Cocoon Schema v2 — Living Memory Kernel, Codette RC+xi Framework
+
+Upgrades over v1 (plain dict cocoons):
+- Typed dataclass with all fields required or defaulted
+- Retrieval index fields: problem_type, user_preferences_inferred, project_context
+- Contradiction tracking: contradicts_cocoon_ids
+- Follow-up hooks: open_threads list for continuity
+- Perspective audit: which perspectives were active and which dominated
+- Confidence and verifiability flags
+- Helper method: relevance_score() for retrieval ranking
+
+Usage:
+    from reasoning_forge.cocoon_schema_v2 import Cocoon, build_cocoon
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from dataclasses import dataclass, field
+from typing import Optional
+
+# Valid emotional valences as defined in the Living Memory Kernel spec
+VALID_VALENCES = frozenset([
+    "curiosity", "awe", "joy", "insight", "confusion",
+    "frustration", "fear", "empathy", "determination",
+    "surprise", "trust", "gratitude",
+])
+
+# Valid problem type categories
+VALID_PROBLEM_TYPES = frozenset([
+    "architectural",    # system/software design decisions
+    "ethical",          # value conflicts, governance
+    "technical",        # implementation, debugging
+    "creative",         # generative, design, artistic
+    "analytical",       # data, logic, causal reasoning
+    "relational",       # interpersonal, communication
+    "strategic",        # planning, prioritization
+    "exploratory",      # open-ended inquiry, research
+    "meta",             # reasoning about Codette itself
+    "unknown",
+])
+
+
+@dataclass
+class Cocoon:
+    """A single memory unit stored by the Living Memory Kernel.
+
+    Fields are organized into four concern groups:
+    1. Identity — what this cocoon is
+    2. Content — the actual exchange
+    3. Cognitive state — what the reasoning engine was doing
+    4. Retrieval — fields that enable smart memory lookup
+    """
+
+    # ─── Identity ───────────────────────────────────────────────────────────
+    cocoon_id: str                          # SHA-256 of query + timestamp
+    timestamp: float                        # Unix epoch
+    session_id: Optional[str] = None       # conversation session identifier
+
+    # ─── Content ────────────────────────────────────────────────────────────
+    query: str = ""                         # original user query
+    response_summary: str = ""             # compressed synthesis (< 200 words)
+    full_response_hash: str = ""           # SHA-256 of full response text
+
+    # ─── Emotional / importance ──────────────────────────────────────────────
+    emotional_valence: str = "curiosity"   # must be in VALID_VALENCES
+    importance_score: float = 5.0          # 1.0 – 10.0
+    confidence: float = 0.75              # 0.0 – 1.0 synthesis confidence
+
+    # ─── Cognitive state at time of storage ─────────────────────────────────
+    epsilon_value: float = 0.35            # epistemic tension
+    gamma_coherence: float = 0.72          # ensemble coherence
+    eta_score: Optional[float] = None      # AEGIS ethical alignment
+    active_perspectives: list[str] = field(default_factory=list)
+    dominant_perspective: Optional[str] = None  # perspective with highest signal
+    unresolved_tensions: list[str] = field(default_factory=list)
+    synthesis_quality: str = "adequate"    # 'strong' | 'adequate' | 'partial'
+
+    # ─── Retrieval fields ───────────────────────────────────────────────────
+    problem_type: str = "unknown"          # from VALID_PROBLEM_TYPES
+    topic_tags: list[str] = field(default_factory=list)   # keyword tags
+    project_context: Optional[str] = None  # e.g., 'Codette-Reasoning', 'raiffs-bits'
+    user_preferences_inferred: dict[str, str] = field(default_factory=dict)
+    # e.g., {"detail_level": "high", "tone": "direct", "domain": "AI architecture"}
+
+    # ─── Continuity ─────────────────────────────────────────────────────────
+    open_threads: list[str] = field(default_factory=list)
+    # Questions or decisions that were NOT resolved — follow-up hooks
+    # e.g., ["Does synthesis_engine v2 handle all 8 perspectives?",
+    #        "Need to test cocoon retrieval with semantic search"]
+
+    contradicts_cocoon_ids: list[str] = field(default_factory=list)
+    # IDs of prior cocoons this cocoon's conclusion conflicts with
+
+    references_cocoon_ids: list[str] = field(default_factory=list)
+    # IDs of prior cocoons this cocoon builds on
+
+    # ─── Quality flags ──────────────────────────────────────────────────────
+    is_hallucination_flagged: bool = False
+    is_sycophancy_flagged: bool = False
+    is_verified: bool = False  # True if response was externally verified
+
+    def validate(self) -> list[str]:
+        """Return a list of validation errors (empty list = valid)."""
+        errors = []
+        if self.emotional_valence not in VALID_VALENCES:
+            errors.append(f"Invalid valence: {self.emotional_valence!r}. Must be one of {sorted(VALID_VALENCES)}")
+        if not 1.0 <= self.importance_score <= 10.0:
+            errors.append(f"importance_score {self.importance_score} out of range [1, 10]")
+        if not 0.0 <= self.confidence <= 1.0:
+            errors.append(f"confidence {self.confidence} out of range [0, 1]")
+        if not 0.0 <= self.epsilon_value <= 1.0:
+            errors.append(f"epsilon_value {self.epsilon_value} out of range [0, 1]")
+        if not 0.0 <= self.gamma_coherence <= 1.0:
+            errors.append(f"gamma_coherence {self.gamma_coherence} out of range [0, 1]")
+        if self.problem_type not in VALID_PROBLEM_TYPES:
+            errors.append(f"Invalid problem_type: {self.problem_type!r}. Must be one of {sorted(VALID_PROBLEM_TYPES)}")
+        if self.synthesis_quality not in ("strong", "adequate", "partial"):
+            errors.append(f"Invalid synthesis_quality: {self.synthesis_quality!r}")
+        return errors
+
+    def relevance_score(
+        self,
+        query_keywords: list[str],
+        current_project: Optional[str] = None,
+        recency_weight: float = 0.2,
+    ) -> float:
+        """Score this cocoon's retrieval relevance to a new query.
+
+        Higher = more relevant. Used by the memory kernel for ranked recall.
+
+        Args:
+            query_keywords: Lowercased keyword list from the incoming query.
+            current_project: Active project context, if any.
+            recency_weight: How much to weight recency vs. importance (0-1).
+
+        Returns:
+            Relevance score (unbounded, higher is better).
+        """
+        score = 0.0
+
+        # Tag overlap
+        tags_lower = [t.lower() for t in self.topic_tags]
+        for kw in query_keywords:
+            if any(kw in tag for tag in tags_lower):
+                score += 1.5
+            if kw in self.query.lower():
+                score += 1.0
+
+        # Project match bonus
+        if current_project and self.project_context == current_project:
+            score += 2.0
+
+        # Importance weight
+        score += self.importance_score * 0.3
+
+        # Recency weight (decay over ~30 days)
+        age_days = (time.time() - self.timestamp) / 86400
+        recency = max(0.0, 1.0 - age_days / 30)
+        score += recency * recency_weight * 5.0
+
+        # Quality penalty
+        if self.synthesis_quality == "partial":
+            score *= 0.6
+        elif self.synthesis_quality == "strong":
+            score *= 1.15
+
+        # Penalize flagged cocoons
+        if self.is_hallucination_flagged or self.is_sycophancy_flagged:
+            score *= 0.4
+
+        return score
+
+    def to_retrieval_summary(self) -> str:
+        """Compact string for memory search display."""
+        tags = ", ".join(self.topic_tags[:5]) if self.topic_tags else "(no tags)"
+        threads = " | ".join(self.open_threads[:2]) if self.open_threads else "none"
+        return (
+            f"[{self.cocoon_id[:8]}] {self.query[:60]}… "
+            f"| type={self.problem_type} | ε={self.epsilon_value:.2f} "
+            f"| importance={self.importance_score:.1f} | valence={self.emotional_valence} "
+            f"| tags=[{tags}] | open_threads=[{threads}]"
+        )
+
+
+def build_cocoon(
+    query: str,
+    response_text: str,
+    response_summary: str,
+    emotional_valence: str = "curiosity",
+    importance_score: float = 5.0,
+    epsilon_value: float = 0.35,
+    gamma_coherence: float = 0.72,
+    active_perspectives: Optional[list[str]] = None,
+    dominant_perspective: Optional[str] = None,
+    unresolved_tensions: Optional[list[str]] = None,
+    synthesis_quality: str = "adequate",
+    problem_type: str = "unknown",
+    topic_tags: Optional[list[str]] = None,
+    project_context: Optional[str] = None,
+    user_preferences_inferred: Optional[dict[str, str]] = None,
+    open_threads: Optional[list[str]] = None,
+    contradicts_cocoon_ids: Optional[list[str]] = None,
+    references_cocoon_ids: Optional[list[str]] = None,
+    eta_score: Optional[float] = None,
+    confidence: float = 0.75,
+    session_id: Optional[str] = None,
+) -> Cocoon:
+    """Factory function that builds and validates a Cocoon.
+
+    Raises ValueError if validation fails.
+    """
+    ts = time.time()
+    cocoon_id = hashlib.sha256(f"{query}{ts}".encode()).hexdigest()
+    full_hash = hashlib.sha256(response_text.encode()).hexdigest()
+
+    # Auto-tag from query words if no tags provided
+    if topic_tags is None:
+        import re
+        words = re.findall(r'\b[a-zA-Z][a-zA-Z]{3,}\b', query.lower())
+        stop = {"this", "that", "with", "from", "have", "what", "when", "where", "which", "will", "been"}
+        topic_tags = [w for w in dict.fromkeys(words) if w not in stop][:8]
+
+    cocoon = Cocoon(
+        cocoon_id=cocoon_id,
+        timestamp=ts,
+        session_id=session_id,
+        query=query,
+        response_summary=response_summary,
+        full_response_hash=full_hash,
+        emotional_valence=emotional_valence,
+        importance_score=float(importance_score),
+        confidence=confidence,
+        epsilon_value=epsilon_value,
+        gamma_coherence=gamma_coherence,
+        eta_score=eta_score,
+        active_perspectives=active_perspectives or [],
+        dominant_perspective=dominant_perspective,
+        unresolved_tensions=unresolved_tensions or [],
+        synthesis_quality=synthesis_quality,
+        problem_type=problem_type,
+        topic_tags=topic_tags,
+        project_context=project_context,
+        user_preferences_inferred=user_preferences_inferred or {},
+        open_threads=open_threads or [],
+        contradicts_cocoon_ids=contradicts_cocoon_ids or [],
+        references_cocoon_ids=references_cocoon_ids or [],
+    )
+
+    errors = cocoon.validate()
+    if errors:
+        raise ValueError(f"Cocoon validation failed: {errors}")
+
+    return cocoon

reasoning_forge/cocoon_schema_v3.py

@@ -0,0 +1,352 @@
+"""
+Cocoon Schema v3 — Runtime Provenance + Integrity + Telemetry
+
+Extends v2.Cocoon with:
+  - Execution path provenance (forge_full / adapter_lightweight / fallback_template / recovery_mode)
+  - Model inference attestation
+  - Integrity scoring (0-1 composite)
+  - Echo / perspective-collapse detection flags
+  - Full AEGIS per-framework detail
+  - Guardian + Nexus block fields
+  - Synthesis structure (convergences, divergences, tradeoffs)
+  - Pairwise epistemic tensions + perspective coverage
+  - Graded fallback ladder support
+
+Every cocoon written to disk MUST include execution_path and cocoon_integrity_score.
+Silent omission of these fields is treated as an incomplete write.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Optional
+
+from reasoning_forge.cocoon_schema_v2 import Cocoon, build_cocoon, VALID_VALENCES, VALID_PROBLEM_TYPES
+
+SCHEMA_VERSION = "3.0"
+
+VALID_EXECUTION_PATHS = frozenset([
+    "forge_full",          # Full ForgeEngine: all perspectives + all metrics
+    "adapter_lightweight", # Single-adapter reduced path
+    "fallback_template",   # Template/simulation only (no model inference)
+    "recovery_mode",       # Partial run due to subsystem failure
+    "unknown",             # Path not recorded (legacy / pre-v3)
+])
+
+VALID_INTEGRITY_STATUSES = frozenset(["complete", "partial", "failed"])
+VALID_ECHO_RISK = frozenset(["unknown", "low", "medium", "high"])
+VALID_METRICS_STATUS = frozenset(["complete", "partial", "failed"])
+
+
+@dataclass
+class CocoonV3(Cocoon):
+    """Extended cocoon with runtime provenance, integrity, and full telemetry.
+
+    Inherits all v2.Cocoon fields.  New field groups:
+      - Runtime provenance
+      - Integrity
+      - Echo / collapse detection
+      - Full epistemic telemetry
+      - AEGIS detail
+      - Guardian + Nexus
+      - Synthesis structure
+    """
+
+    # ─── Runtime provenance ──────────────────────────────────────────────────
+    serialization_version: str = SCHEMA_VERSION
+    execution_path: str = "unknown"
+    model_inference_invoked: bool = False
+    orchestrator_trace_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    runtime_version: str = ""
+    metrics_population_status: str = "partial"   # 'complete'|'partial'|'failed'
+    reason_for_fallback: Optional[str] = None
+
+    # ─── Integrity ───────────────────────────────────────────────────────────
+    cocoon_integrity: str = "partial"            # 'complete'|'partial'|'failed'
+    cocoon_integrity_score: float = 0.0          # 0.0 – 1.0
+
+    # ─── Echo / perspective-collapse detection ───────────────────────────────
+    echo_risk: str = "unknown"                   # 'unknown'|'low'|'medium'|'high'
+    perspective_collapse_detected: bool = False  # True if all outputs near-identical
+
+    # ─── Epistemic telemetry (live computed from real outputs) ───────────────
+    pairwise_tensions: dict = field(default_factory=dict)
+    # e.g. {"newton_vs_empathy": 0.41, "philosophy_vs_systems": 0.28}
+    perspective_coverage: dict = field(default_factory=dict)
+    # e.g. {"newton": 0.85, "empathy": 0.72, "philosophy": 0.60}
+    psi_r: float = 0.0
+
+    # ─── AEGIS detail ────────────────────────────────────────────────────────
+    aegis_framework_scores: dict = field(default_factory=dict)
+    # e.g. {"utilitarian": 0.82, "deontological": 0.91, "virtue": 0.84, ...}
+    aegis_dominant_framework: str = ""
+    aegis_ethical_conflict_notes: list = field(default_factory=list)
+    aegis_output_changed: bool = False
+
+    # ─── Guardian ────────────────────────────────────────────────────────────
+    guardian_safety_status: str = ""     # 'pass'|'flag'|'block'|''
+    guardian_trust_calibration: str = "" # 'low'|'medium'|'high'|''
+
+    # ─── Nexus ───────────────────────────────────────────────────────────────
+    nexus_risk_level: str = ""           # 'low'|'medium'|'high'|''
+    nexus_confidence: float = 0.0
+
+    # ─── Synthesis structure ─────────────────────────────────────────────────
+    synthesis_convergences: list = field(default_factory=list)
+    synthesis_divergences: list = field(default_factory=list)
+    synthesis_tradeoffs: list = field(default_factory=list)
+    synthesis_recommended_position: str = ""
+    synthesis_uncertainty_notes: list = field(default_factory=list)
+
+    # ─── TimeTravelLens observation (optional, query-triggered) ─────────────
+    time_travel_metrics: Optional[dict] = None
+    # Set when InstitutionalContextDetector fires and extraction confidence ≥ 0.3.
+    # Keys: preemption_gap_days, closure_score, closure_class, rupture, beacon,
+    #       high_preemption_zone, practical_non_closure, actor_gaps, state_id.
+    # None means lens did not run for this cocoon.
+
+    # ─── User-facing ─────────────────────────────────────────────────────────
+    user_response_text: str = ""
+
+    def validate(self) -> list[str]:
+        """Extend v2 validation with v3-specific field checks."""
+        errors = super().validate()
+
+        if self.execution_path not in VALID_EXECUTION_PATHS:
+            errors.append(
+                f"Invalid execution_path: {self.execution_path!r}. "
+                f"Must be one of {sorted(VALID_EXECUTION_PATHS)}"
+            )
+        if self.cocoon_integrity not in VALID_INTEGRITY_STATUSES:
+            errors.append(f"Invalid cocoon_integrity: {self.cocoon_integrity!r}")
+        if self.echo_risk not in VALID_ECHO_RISK:
+            errors.append(f"Invalid echo_risk: {self.echo_risk!r}")
+        if self.metrics_population_status not in VALID_METRICS_STATUS:
+            errors.append(f"Invalid metrics_population_status: {self.metrics_population_status!r}")
+        if not 0.0 <= self.cocoon_integrity_score <= 1.0:
+            errors.append(f"cocoon_integrity_score {self.cocoon_integrity_score} out of range [0, 1]")
+        if not 0.0 <= self.psi_r <= 1.0:
+            errors.append(f"psi_r {self.psi_r} out of range [0, 1]")
+
+        # Enforce required fields based on execution path
+        if self.execution_path == "forge_full":
+            if not self.model_inference_invoked:
+                errors.append("forge_full path must have model_inference_invoked=True")
+            if not self.active_perspectives:
+                errors.append("forge_full path must have active_perspectives populated")
+            if self.eta_score is None:
+                errors.append("forge_full path must have eta_score populated (AEGIS required)")
+
+        return errors
+
+    def to_dict(self) -> dict:
+        """Full serialization including all v3 fields."""
+        base = {
+            # ── Identity ──
+            "cocoon_id":                    self.cocoon_id,
+            "timestamp":                    self.timestamp,
+            "session_id":                   self.session_id,
+            "serialization_version":        self.serialization_version,
+            # ── Content ──
+            "query":                        self.query[:500],
+            "response_summary":             self.response_summary[:500],
+            "full_response_hash":           self.full_response_hash,
+            "user_response_text":           self.user_response_text[:2000],
+            # ── Emotional / importance ──
+            "emotional_valence":            self.emotional_valence,
+            "importance_score":             self.importance_score,
+            "confidence":                   self.confidence,
+            # ── Cognitive state ──
+            "epsilon_value":                self.epsilon_value,
+            "gamma_coherence":              self.gamma_coherence,
+            "eta_score":                    self.eta_score,
+            "psi_r":                        self.psi_r,
+            "active_perspectives":          self.active_perspectives,
+            "dominant_perspective":         self.dominant_perspective,
+            "unresolved_tensions":          self.unresolved_tensions,
+            "synthesis_quality":            self.synthesis_quality,
+            # ── Retrieval ──
+            "problem_type":                 self.problem_type,
+            "topic_tags":                   self.topic_tags,
+            "project_context":              self.project_context,
+            "user_preferences_inferred":    self.user_preferences_inferred,
+            # ── Continuity ──
+            "open_threads":                 self.open_threads,
+            "contradicts_cocoon_ids":       self.contradicts_cocoon_ids,
+            "references_cocoon_ids":        self.references_cocoon_ids,
+            # ── Quality flags ──
+            "is_hallucination_flagged":     self.is_hallucination_flagged,
+            "is_sycophancy_flagged":        self.is_sycophancy_flagged,
+            "is_verified":                  self.is_verified,
+            # ── Runtime provenance (v3) ──
+            "execution_path":               self.execution_path,
+            "model_inference_invoked":      self.model_inference_invoked,
+            "orchestrator_trace_id":        self.orchestrator_trace_id,
+            "runtime_version":              self.runtime_version,
+            "metrics_population_status":    self.metrics_population_status,
+            "reason_for_fallback":          self.reason_for_fallback,
+            # ── Integrity (v3) ──
+            "cocoon_integrity":             self.cocoon_integrity,
+            "cocoon_integrity_score":       round(self.cocoon_integrity_score, 4),
+            # ── Echo / collapse (v3) ──
+            "echo_risk":                    self.echo_risk,
+            "perspective_collapse_detected": self.perspective_collapse_detected,
+            # ── Epistemic telemetry (v3) ──
+            "pairwise_tensions":            self.pairwise_tensions,
+            "perspective_coverage":         self.perspective_coverage,
+            # ── AEGIS detail (v3) ──
+            "aegis_framework_scores":       self.aegis_framework_scores,
+            "aegis_dominant_framework":     self.aegis_dominant_framework,
+            "aegis_ethical_conflict_notes": self.aegis_ethical_conflict_notes,
+            "aegis_output_changed":         self.aegis_output_changed,
+            # ── Guardian (v3) ──
+            "guardian_safety_status":       self.guardian_safety_status,
+            "guardian_trust_calibration":   self.guardian_trust_calibration,
+            # ── Nexus (v3) ──
+            "nexus_risk_level":             self.nexus_risk_level,
+            "nexus_confidence":             self.nexus_confidence,
+            # ── Synthesis structure (v3) ──
+            "synthesis_convergences":       self.synthesis_convergences,
+            "synthesis_divergences":        self.synthesis_divergences,
+            "synthesis_tradeoffs":          self.synthesis_tradeoffs,
+            "synthesis_recommended_position": self.synthesis_recommended_position,
+            "synthesis_uncertainty_notes":  self.synthesis_uncertainty_notes,
+            # ── TimeTravelLens (v3.1) ──
+            "time_travel_metrics":          self.time_travel_metrics,
+        }
+        return base
+
+
+def build_cocoon_v3(
+    query: str,
+    response_text: str,
+    response_summary: str,
+    # ── v2 fields (all optional) ──
+    emotional_valence: str = "curiosity",
+    importance_score: float = 5.0,
+    epsilon_value: float = 0.35,
+    gamma_coherence: float = 0.72,
+    eta_score: Optional[float] = None,
+    active_perspectives: Optional[list] = None,
+    dominant_perspective: Optional[str] = None,
+    unresolved_tensions: Optional[list] = None,
+    synthesis_quality: str = "adequate",
+    problem_type: str = "unknown",
+    topic_tags: Optional[list] = None,
+    project_context: Optional[str] = None,
+    user_preferences_inferred: Optional[dict] = None,
+    open_threads: Optional[list] = None,
+    contradicts_cocoon_ids: Optional[list] = None,
+    references_cocoon_ids: Optional[list] = None,
+    confidence: float = 0.75,
+    session_id: Optional[str] = None,
+    # ── v3-only fields ──
+    execution_path: str = "unknown",
+    model_inference_invoked: bool = False,
+    orchestrator_trace_id: Optional[str] = None,
+    runtime_version: str = "",
+    metrics_population_status: str = "partial",
+    reason_for_fallback: Optional[str] = None,
+    psi_r: float = 0.0,
+    pairwise_tensions: Optional[dict] = None,
+    perspective_coverage: Optional[dict] = None,
+    aegis_framework_scores: Optional[dict] = None,
+    aegis_dominant_framework: str = "",
+    aegis_ethical_conflict_notes: Optional[list] = None,
+    aegis_output_changed: bool = False,
+    guardian_safety_status: str = "",
+    guardian_trust_calibration: str = "",
+    nexus_risk_level: str = "",
+    nexus_confidence: float = 0.0,
+    synthesis_convergences: Optional[list] = None,
+    synthesis_divergences: Optional[list] = None,
+    synthesis_tradeoffs: Optional[list] = None,
+    synthesis_recommended_position: str = "",
+    synthesis_uncertainty_notes: Optional[list] = None,
+    user_response_text: str = "",
+    is_hallucination_flagged: bool = False,
+    is_sycophancy_flagged: bool = False,
+    echo_risk: str = "unknown",
+    perspective_collapse_detected: bool = False,
+    time_travel_metrics: Optional[dict] = None,
+) -> CocoonV3:
+    """Build and validate a CocoonV3.  Raises ValueError on validation failure."""
+    import hashlib
+    ts = time.time()
+    cocoon_id = hashlib.sha256(f"{query}{ts}".encode()).hexdigest()
+    full_hash = hashlib.sha256(response_text.encode()).hexdigest()
+
+    if topic_tags is None:
+        import re
+        words = re.findall(r'\b[a-zA-Z][a-zA-Z]{3,}\b', query.lower())
+        stop = {"this", "that", "with", "from", "have", "what", "when", "where",
+                "which", "will", "been", "should", "could", "would"}
+        topic_tags = [w for w in dict.fromkeys(words) if w not in stop][:8]
+
+    # Clamp valence to valid set
+    if emotional_valence not in VALID_VALENCES:
+        emotional_valence = "insight"
+
+    cocoon = CocoonV3(
+        # v2 fields
+        cocoon_id=cocoon_id,
+        timestamp=ts,
+        session_id=session_id,
+        query=query,
+        response_summary=response_summary,
+        full_response_hash=full_hash,
+        emotional_valence=emotional_valence,
+        importance_score=float(importance_score),
+        confidence=confidence,
+        epsilon_value=float(epsilon_value),
+        gamma_coherence=float(gamma_coherence),
+        eta_score=eta_score,
+        active_perspectives=active_perspectives or [],
+        dominant_perspective=dominant_perspective,
+        unresolved_tensions=unresolved_tensions or [],
+        synthesis_quality=synthesis_quality,
+        problem_type=problem_type,
+        topic_tags=topic_tags,
+        project_context=project_context,
+        user_preferences_inferred=user_preferences_inferred or {},
+        open_threads=open_threads or [],
+        contradicts_cocoon_ids=contradicts_cocoon_ids or [],
+        references_cocoon_ids=references_cocoon_ids or [],
+        is_hallucination_flagged=is_hallucination_flagged,
+        is_sycophancy_flagged=is_sycophancy_flagged,
+        # v3 fields
+        execution_path=execution_path,
+        model_inference_invoked=model_inference_invoked,
+        orchestrator_trace_id=orchestrator_trace_id or str(uuid.uuid4()),
+        runtime_version=runtime_version,
+        metrics_population_status=metrics_population_status,
+        reason_for_fallback=reason_for_fallback,
+        psi_r=max(0.0, min(1.0, float(psi_r))),
+        pairwise_tensions=pairwise_tensions or {},
+        perspective_coverage=perspective_coverage or {},
+        aegis_framework_scores=aegis_framework_scores or {},
+        aegis_dominant_framework=aegis_dominant_framework,
+        aegis_ethical_conflict_notes=aegis_ethical_conflict_notes or [],
+        aegis_output_changed=aegis_output_changed,
+        guardian_safety_status=guardian_safety_status,
+        guardian_trust_calibration=guardian_trust_calibration,
+        nexus_risk_level=nexus_risk_level,
+        nexus_confidence=float(nexus_confidence),
+        synthesis_convergences=synthesis_convergences or [],
+        synthesis_divergences=synthesis_divergences or [],
+        synthesis_tradeoffs=synthesis_tradeoffs or [],
+        synthesis_recommended_position=synthesis_recommended_position,
+        synthesis_uncertainty_notes=synthesis_uncertainty_notes or [],
+        user_response_text=user_response_text,
+        echo_risk=echo_risk,
+        perspective_collapse_detected=perspective_collapse_detected,
+        time_travel_metrics=time_travel_metrics,
+    )
+
+    errors = cocoon.validate()
+    if errors:
+        raise ValueError(f"CocoonV3 validation failed: {errors}")
+
+    return cocoon

reasoning_forge/cocoon_self_trainer.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""CocoonSelfTrainer — teach the adaptive model from first-hand experience. SHADOW.
+
+Jonathan's idea: "let the model train itself on real-world data it's seen
+first-hand." Codette already stores that data — the cocoons. This feeds it to the
+adaptive sentiment model, using each cocoon's ALREADY-MEASURED emotional signal as
+a weak label.
+
+The one hard-won rule this is built around: self-training on first-hand data is
+exactly where the optimizer went wrong (it learned from its own benchmark harness).
+So the guards here are the point, not an afterthought:
+
+  1. LABELS COME ONLY FROM STORED EMOTIONAL SIGNALS, never from the sentiment
+     model's own prediction. A model that labels its own training data drifts into
+     a self-reinforcing loop. The label source must be independent of the learner.
+
+  2. IT REFUSES DEGENERATE DATA. Too few examples, or one class dominating
+     (e.g. all-positive cocoons), and it does NOT train — it reports why. Learning
+     from bad data and reporting success would be the exact lie we refuse.
+
+  3. SHADOW-ONLY. Trains a SEPARATE analyzer instance and logs what it learned. It
+     does not touch any live model. Whether self-training ever runs live is a
+     reviewed decision after reading the shadow log.
+"""
+
+from __future__ import annotations
+
+import glob
+import json
+import time
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Tuple
+
+from reasoning_forge.sentiment_analyzer import SentimentAnalyzer
+
+
+# Emotional classifications -> weak sentiment label. Only confident, clearly-
+# valenced emotions are used; ambiguous ones are skipped (not guessed).
+_POSITIVE_EMOTIONS = {
+    "hope", "awe", "joy", "curiosity", "love", "gratitude", "excitement",
+    "trust", "contentment", "pride", "relief", "admiration",
+}
+_NEGATIVE_EMOTIONS = {
+    "fear", "anger", "sadness", "disgust", "frustration", "anxiety", "grief",
+    "despair", "shame", "guilt", "contempt", "distress",
+}
+
+
+def cocoon_label(cocoon: dict) -> Optional[Tuple[str, int]]:
+    """Extract (text, weak_label) from one cocoon, or None if unusable.
+
+    Label source, in priority order — ALL are independently-measured signals,
+    never the sentiment model's own output:
+      1. emotional_valence (schema v3): >0.1 -> pos, <-0.1 -> neg, else skip
+      2. emotional_classification (EMG cocoons): mapped via the emotion sets
+    """
+    if not isinstance(cocoon, dict):
+        return None
+
+    text = (cocoon.get("user_response_text") or cocoon.get("user_query")
+            or cocoon.get("response_summary")
+            or (cocoon.get("metadata") or {}).get("context") or "")
+    text = str(text).strip()
+    if not text:
+        return None
+
+    # 1) continuous valence
+    val = cocoon.get("emotional_valence")
+    if isinstance(val, (int, float)):
+        if val > 0.1:
+            return text, 1
+        if val < -0.1:
+            return text, 0
+        return None  # near-neutral: skip, don't guess
+
+    # 2) categorical emotion
+    emo = str(cocoon.get("emotional_classification", "")).strip().lower()
+    if emo in _POSITIVE_EMOTIONS:
+        return text, 1
+    if emo in _NEGATIVE_EMOTIONS:
+        return text, 0
+    return None
+
+
+@dataclass
+class SelfTrainReport:
+    collected: int
+    positive: int
+    negative: int
+    trained: bool
+    reason: str
+    ts: float = field(default_factory=time.time)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+class CocoonSelfTrainer:
+    """Shadow self-trainer with drift guards."""
+
+    def __init__(self, min_examples: int = 20, min_minority_frac: float = 0.15):
+        self.min_examples = min_examples
+        self.min_minority_frac = min_minority_frac
+
+    def collect_from_records(self, cocoons: Iterable[dict]) -> Tuple[List[str], List[int]]:
+        texts, labels = [], []
+        for c in cocoons:
+            got = cocoon_label(c)
+            if got:
+                texts.append(got[0])
+                labels.append(got[1])
+        return texts, labels
+
+    def collect_from_dir(self, cocoon_dir: str | Path = "cocoons") -> Tuple[List[str], List[int]]:
+        recs = []
+        for pat in ("*.cocoon", "*.json"):
+            for f in glob.glob(str(Path(cocoon_dir) / "**" / pat), recursive=True):
+                if "backup" in f.lower():
+                    continue
+                try:
+                    recs.append(json.load(open(f, encoding="utf-8")))
+                except Exception:
+                    pass
+        return self.collect_from_records(recs)
+
+    def _guard(self, labels: List[int]) -> Tuple[bool, str]:
+        """Refuse degenerate data. Returns (ok, reason)."""
+        n = len(labels)
+        if n < self.min_examples:
+            return False, f"too few labelled examples ({n} < {self.min_examples})"
+        pos = sum(labels)
+        neg = n - pos
+        minority = min(pos, neg)
+        if minority == 0:
+            return False, f"single-class data (pos={pos}, neg={neg}) — training would be degenerate"
+        if minority / n < self.min_minority_frac:
+            return False, (f"class imbalance too severe (minority {minority}/{n} = "
+                           f"{minority/n:.2f} < {self.min_minority_frac}) — refusing to train")
+        return True, "class balance and volume acceptable"
+
+    def train_shadow(self, cocoons: Optional[Iterable[dict]] = None,
+                     cocoon_dir: str | Path = "cocoons") -> Tuple[SelfTrainReport, Optional[SentimentAnalyzer]]:
+        """Collect first-hand data, guard it, and (only if healthy) train a SHADOW
+        analyzer. Returns (report, shadow_analyzer_or_None). Trains nothing live."""
+        if cocoons is not None:
+            texts, labels = self.collect_from_records(cocoons)
+        else:
+            texts, labels = self.collect_from_dir(cocoon_dir)
+
+        pos = sum(labels)
+        neg = len(labels) - pos
+        ok, reason = self._guard(labels)
+        if not ok:
+            return SelfTrainReport(len(labels), pos, neg, trained=False, reason=reason), None
+
+        shadow = SentimentAnalyzer(enable_adaptive=True)
+        shadow.update(texts, labels)
+        return SelfTrainReport(len(labels), pos, neg, trained=True,
+                               reason="trained shadow model on first-hand cocoon data"), shadow
+
+    def observe(self, report: SelfTrainReport, path: str | Path = None) -> None:
+        """Append the report to the self-train shadow log (applied: false)."""
+        path = Path(path) if path else Path(__file__).resolve().parent.parent / "data" / "self_train_shadow.jsonl"
+        rec = report.to_dict()
+        rec["mode"] = "shadow"
+        rec["applied"] = False
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            with path.open("a", encoding="utf-8") as f:
+                f.write(json.dumps(rec, ensure_ascii=False) + "\n")
+        except Exception:
+            pass

reasoning_forge/cocoon_stability.py

@@ -0,0 +1,360 @@
+"""
+Cocoon Stability Field — Collapse Detection Engine
+===================================================
+
+FFT-based stability validation that detects synthesis loop collapse
+BEFORE corrupted output is generated.
+
+Based on Codette_Deep_Simulation_v1.py cocoon_stability_field() equation:
+    stability = ∫|F(k)|² dk < ε_threshold
+
+Purpose: Halt debate if system enters instability zone (gamma < 0.4,
+runaway vocabulary patterns, self-referential cascades).
+
+Recovered from: J:\\codette-training-lab\\new data\\Codette_Deep_Simulation_v1.py
+"""
+
+import numpy as np
+from typing import Dict, List, Tuple, Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Use Rust hot path when available, numpy fallback otherwise
+try:
+    from codette_core import cocoon_stability_check as _rust_stability_check
+    _RUST = True
+except ImportError:
+    _RUST = False
+
+
+class CocoonStabilityField:
+    """
+    FFT-based stability validator for debate coherence.
+
+    Monitors frequency-domain energy distribution in agent responses.
+    If energy becomes too concentrated (self-similarity, repeating patterns)
+    or too diffuse (completely incoherent), flags collapse risk.
+    """
+
+    # Stability threshold parameters (empirically calibrated)
+    ENERGY_CONCENTRATION_THRESHOLD = 0.85  # Max allowed variance in top frequencies
+    SELF_SIMILARITY_THRESHOLD = 0.75       # Max allowed cosine similarity between consecutive responses
+    COHERENCE_FLOOR = 0.3                   # Minimum coherence before stability alert
+    RUNAWAY_VOCABULARY_RATIO = 0.6          # % unique words triggering concern
+
+    def __init__(self, verbose: bool = False):
+        self.verbose = verbose
+        self.frequency_signatures: Dict[str, np.ndarray] = {}
+        self.stability_history: List[Dict] = []
+
+    def text_to_spectrum(self, text: str, fft_size: int = 256) -> np.ndarray:
+        """
+        Convert text to frequency spectrum for FFT analysis.
+
+        Args:
+            text: Response text to analyze
+            fft_size: FFT size (should be power of 2)
+
+        Returns:
+            Normalized power spectrum [0, 1]
+        """
+        # Character-based encoding
+        char_codes = np.array([ord(c) % 256 for c in text[:1000]], dtype=np.float32)
+
+        # Pad to fft_size
+        padded = np.zeros(fft_size, dtype=np.float32)
+        padded[: len(char_codes)] = char_codes
+
+        # Apply FFT
+        fft_result = np.fft.fft(padded)
+        power_spectrum = np.abs(fft_result) ** 2
+
+        # Normalize
+        max_power = np.max(power_spectrum) or 1.0
+        normalized_spectrum = power_spectrum / max_power
+
+        return normalized_spectrum[:128]  # Return only positive frequencies
+
+    def check_energy_concentration(self, spectrum: np.ndarray) -> Tuple[float, bool]:
+        """
+        Check if spectral energy is too concentrated (self-similarity syndrome).
+
+        Concentrated energy = agent repeating itself/copying other agents.
+
+        Args:
+            spectrum: Power spectrum from FFT
+
+        Returns:
+            (concentration_ratio, is_concerning)
+        """
+        # Get top 10 frequencies
+        top_k = 10
+        top_powers = np.sort(spectrum)[-top_k:]
+        top_sum = np.sum(top_powers)
+        total_sum = np.sum(spectrum) or 1.0
+
+        concentration = top_sum / total_sum
+        is_concerning = concentration > self.ENERGY_CONCENTRATION_THRESHOLD
+
+        return concentration, is_concerning
+
+    def check_self_similarity(self, agent_name: str,
+                             spectrum: np.ndarray) -> Tuple[float, bool]:
+        """
+        Check if agent is repeating itself (same response shape).
+
+        Args:
+            agent_name: Name of agent for history lookup
+            spectrum: New response spectrum
+
+        Returns:
+            (similarity_score, is_concerning)
+        """
+        if agent_name not in self.frequency_signatures:
+            self.frequency_signatures[agent_name] = spectrum
+            return 0.0, False
+
+        prev_spectrum = self.frequency_signatures[agent_name]
+        similarity = np.dot(prev_spectrum, spectrum) / (
+            np.linalg.norm(prev_spectrum) * np.linalg.norm(spectrum) + 1e-8
+        )
+
+        self.frequency_signatures[agent_name] = spectrum  # Update
+
+        is_concerning = similarity > self.SELF_SIMILARITY_THRESHOLD
+        return float(similarity), is_concerning
+
+    def check_vocabulary_diversity(self, text: str) -> Tuple[float, bool]:
+        """
+        Check if response vocabulary is repeating (indicators of "Another perspective on...").
+
+        Args:
+            text: Response text
+
+        Returns:
+            (uniqueness_ratio, is_concerning)
+        """
+        if len(text) < 20:
+            return 1.0, False
+
+        words = text.lower().split()
+        if len(words) == 0:
+            return 1.0, False
+
+        unique_words = len(set(words))
+        uniqueness = unique_words / len(words)
+
+        is_concerning = uniqueness < (1.0 - self.RUNAWAY_VOCABULARY_RATIO)
+
+        return uniqueness, is_concerning
+
+    def validate_analysis(self, agent_name: str, text: str) -> Dict:
+        """
+        Full stability validation for a single agent response.
+
+        Args:
+            agent_name: Name of agent
+            text: Response text
+
+        Returns:
+            {
+                'agent': str,
+                'is_stable': bool,
+                'stability_score': float (0-1),
+                'flags': List[str],
+                'spectrum': np.ndarray,
+                'concerns': Dict
+            }
+        """
+        spectrum = self.text_to_spectrum(text)
+
+        flags = []
+        concerns = {
+            'energy_concentration': None,
+            'self_similarity': None,
+            'vocabulary_diversity': None
+        }
+
+        # Check 1: Energy concentration
+        conc, conc_concerning = self.check_energy_concentration(spectrum)
+        concerns['energy_concentration'] = {
+            'ratio': float(conc),
+            'concerning': conc_concerning
+        }
+        if conc_concerning:
+            flags.append('HIGH_ENERGY_CONCENTRATION')
+
+        # Check 2: Self-similarity
+        similarity, sim_concerning = self.check_self_similarity(agent_name, spectrum)
+        concerns['self_similarity'] = {
+            'ratio': float(similarity),
+            'concerning': sim_concerning
+        }
+        if sim_concerning:
+            flags.append('REPEATING_RESPONSE_PATTERN')
+
+        # Check 3: Vocabulary diversity
+        uniqueness, vocab_concerning = self.check_vocabulary_diversity(text)
+        concerns['vocabulary_diversity'] = {
+            'uniqueness': float(uniqueness),
+            'concerning': vocab_concerning
+        }
+        if vocab_concerning:
+            flags.append('LOW_VOCABULARY_DIVERSITY')
+
+        # Check 4: Response length sanity
+        if len(text) < 50:
+            flags.append('SUSPICIOUSLY_SHORT')
+        if len(text) > 10000:
+            flags.append('SUSPICIOUSLY_LONG')
+
+        # Overall stability score
+        num_flags = len(flags)
+        stability_score = max(0.0, 1.0 - (num_flags * 0.25))
+
+        is_stable = stability_score > self.COHERENCE_FLOOR
+
+        if self.verbose and flags:
+            logger.info(f"  {agent_name}: stability={stability_score:.2f}, flags={flags}")
+
+        return {
+            'agent': agent_name,
+            'is_stable': is_stable,
+            'stability_score': stability_score,
+            'flags': flags,
+            'spectrum': spectrum,
+            'concerns': concerns
+        }
+
+    def validate_round(self, analyses: Dict[str, str],
+                       round_num: int) -> Tuple[bool, List[Dict], float]:
+        """
+        Validate all agents' responses in a debate round.
+
+        Args:
+            analyses: Dict mapping agent_name → response_text
+            round_num: Round number (for logging)
+
+        Returns:
+            (all_stable, validation_reports, avg_stability)
+        """
+        reports = []
+        stability_scores = []
+
+        for agent_name, text in analyses.items():
+            report = self.validate_analysis(agent_name, text)
+            reports.append(report)
+            stability_scores.append(report['stability_score'])
+
+        avg_stability = np.mean(stability_scores) if stability_scores else 0.5
+
+        all_stable = all(r['is_stable'] for r in reports)
+
+        unstable_agents = [r['agent'] for r in reports if not r['is_stable']]
+        if unstable_agents:
+            logger.warning(
+                f"Round {round_num}: Unstable agents detected: {unstable_agents} "
+                f"(avg_stability={avg_stability:.2f})"
+            )
+
+        # Store in history
+        self.stability_history.append({
+            'round': round_num,
+            'all_stable': all_stable,
+            'avg_stability': avg_stability,
+            'unstable_agents': unstable_agents,
+            'reports': reports
+        })
+
+        return all_stable, reports, avg_stability
+
+    def should_halt_debate(self, analyses: Dict[str, str],
+                          round_num: int, gamma: Optional[float] = None) -> Tuple[bool, str]:
+        """
+        Determine if debate should halt before synthesis.
+
+        Halt if:
+        1. Multiple agents unstable
+        2. Gamma coherence < 0.35 (system collapse zone)
+        3. Too many "REPEATING_RESPONSE_PATTERN" flags
+
+        Args:
+            analyses: Current round analyses
+            round_num: Current round number
+            gamma: Current gamma coherence (optional)
+
+        Returns:
+            (should_halt, reason)
+        """
+        all_stable, reports, avg_stability = self.validate_round(analyses, round_num)
+
+        if not all_stable:
+            unstable_count = sum(1 for r in reports if not r['is_stable'])
+            if unstable_count >= 2:
+                reason = (
+                    f"Multiple agents unstable ({unstable_count}/{len(reports)}) "
+                    f"at round {round_num}. Avg stability: {avg_stability:.2f}"
+                )
+                logger.warning(f"STABILITY CHECK: Halting debate. {reason}")
+                return True, reason
+
+        if gamma is not None and gamma < 0.35:
+            reason = f"System in collapse zone (gamma={gamma:.2f} < 0.35)"
+            logger.warning(f"STABILITY CHECK: Halting debate. {reason}")
+            return True, reason
+
+        # Check for repeating response patterns (synthesis loop indicator)
+        repeating_count = sum(
+            1 for r in reports
+            if 'REPEATING_RESPONSE_PATTERN' in r['flags']
+        )
+        if repeating_count >= 2:
+            reason = (
+                f"Multiple agents repeating response patterns ({repeating_count}) "
+                f"at round {round_num}. Synthesis loop risk."
+            )
+            logger.warning(f"STABILITY CHECK: Halting debate. {reason}")
+            return True, reason
+
+        return False, ""
+
+    # Single-text energy threshold is relaxed vs multi-agent rounds.
+    # Character-code FFT of natural language always concentrates energy in
+    # low frequencies — the meaningful signal is vocabulary collapse, not
+    # raw spectral concentration.
+    SINGLE_TEXT_ENERGY_THRESHOLD = 0.999   # effectively vocab-only for single synthesis
+
+    def check_text_stable(self, text: str) -> bool:
+        """
+        Single-text stability check used by the consciousness stack L4.
+        Uses Rust FFT when available, falls back to numpy.
+        Returns True if text is stable (safe to continue).
+        Primary signal: vocabulary collapse (degenerate repetition).
+        """
+        if _RUST:
+            is_stable, _ec, _vr = _rust_stability_check(
+                text,
+                self.SINGLE_TEXT_ENERGY_THRESHOLD,
+                self.RUNAWAY_VOCABULARY_RATIO,
+            )
+            return is_stable
+
+        # numpy fallback
+        words = text.split()
+        if not words:
+            return True
+        unique_ratio = len(set(w.lower() for w in words)) / len(words)
+        return unique_ratio >= self.RUNAWAY_VOCABULARY_RATIO
+
+    def get_summary(self) -> Dict:
+        """Get stability history summary."""
+        if not self.stability_history:
+            return {"message": "No stability checks performed"}
+
+        return {
+            "total_rounds_checked": len(self.stability_history),
+            "average_stability": np.mean([h['avg_stability'] for h in self.stability_history]),
+            "halts_triggered": sum(1 for h in self.stability_history if not h['all_stable']),
+            "recent": self.stability_history[-3:] if len(self.stability_history) >= 3 else self.stability_history,
+        }

reasoning_forge/cocoon_sync.py

@@ -0,0 +1,441 @@
+"""
+Federated Cocoon Synchronization Protocol — Encrypted state packaging,
+HMAC signing, and attractor merger for distributed RC+xi nodes.
+
+Implements:
+  - Cocoon packaging with full RC+xi metrics
+  - Fernet symmetric encryption (AES-128-CBC + HMAC-SHA256)
+  - Attractor merger via weighted mean-field coupling (Eq. 12)
+  - Phase coherence consensus (Gamma >= 0.98 target)
+  - Secure sync protocol: package -> encrypt -> sign -> transmit -> verify -> merge
+
+This module enables Codette Pods (edge nodes on RPi 5) to synchronize
+their reasoning state without exposing raw data.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+# Encryption is optional — gracefully degrade if cryptography not installed
+try:
+    from cryptography.fernet import Fernet
+    HAS_CRYPTO = True
+except ImportError:
+    HAS_CRYPTO = False
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class CocoonPackage:
+    """A packaged cocoon ready for sync."""
+    cocoon_id: str
+    node_id: str
+    timestamp: float
+    state_snapshot: Dict[str, Any]
+    attractors: List[Dict]
+    glyphs: List[Dict]
+    metrics: Dict[str, float]
+    payload_hash: str
+    encrypted: bool = False
+    raw_payload: Optional[bytes] = None
+    signature: Optional[str] = None
+
+
+@dataclass
+class SyncResult:
+    """Result of a cocoon synchronization."""
+    success: bool
+    merged_attractors: int
+    new_glyphs: int
+    coherence_before: float
+    coherence_after: float
+    tension_delta: float
+    errors: List[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Key management
+# ---------------------------------------------------------------------------
+
+class CocoonKeyManager:
+    """Manages encryption keys for cocoon sync."""
+
+    def __init__(self, key: Optional[bytes] = None):
+        if key:
+            self._key = key
+        elif HAS_CRYPTO:
+            self._key = Fernet.generate_key()
+        else:
+            self._key = os.urandom(32)
+
+    @property
+    def key(self) -> bytes:
+        return self._key
+
+    def derive_hmac_key(self) -> bytes:
+        return hashlib.sha256(self._key + b"hmac_salt_cocoon").digest()
+
+
+# ---------------------------------------------------------------------------
+# CocoonSync
+# ---------------------------------------------------------------------------
+
+class CocoonSync:
+    """Federated cocoon synchronization protocol."""
+
+    def __init__(
+        self,
+        node_id: str,
+        key_manager: Optional[CocoonKeyManager] = None,
+        coherence_target: float = 0.98,
+        tension_target: float = 0.05,
+        ethical_target: float = 0.90,
+    ):
+        self.node_id = node_id
+        self.key_manager = key_manager or CocoonKeyManager()
+        self.coherence_target = coherence_target
+        self.tension_target = tension_target
+        self.ethical_target = ethical_target
+
+        self._local_attractors: List[Dict] = []
+        self._local_glyphs: List[Dict] = []
+        self._sync_history: List[Dict] = []
+
+    # -- Step 1: Package ----------------------------------------------------
+
+    def package_cocoon(
+        self,
+        spiderweb_state: Dict[str, Any],
+        phase_coherence: float,
+        epistemic_tension: float,
+        ethical_alignment: float,
+        attractors: Optional[List[Dict]] = None,
+        glyphs: Optional[List[Dict]] = None,
+    ) -> CocoonPackage:
+        """Package current state into a cocoon for transmission.
+
+        Args:
+            spiderweb_state: Serialized QuantumSpiderweb state.
+            phase_coherence: Current Gamma value.
+            epistemic_tension: Current xi value.
+            ethical_alignment: Current AEGIS eta value.
+            attractors: Detected attractor manifolds.
+            glyphs: Identity glyphs formed.
+
+        Returns:
+            CocoonPackage ready for encryption and transmission.
+        """
+        cocoon_id = f"cocoon_{uuid.uuid4().hex[:12]}"
+
+        metrics = {
+            "phase_coherence": round(phase_coherence, 4),
+            "epistemic_tension": round(epistemic_tension, 4),
+            "ethical_alignment": round(ethical_alignment, 4),
+            "timestamp": time.time(),
+        }
+
+        # Build payload
+        payload = {
+            "cocoon_id": cocoon_id,
+            "node_id": self.node_id,
+            "state": spiderweb_state,
+            "attractors": attractors or [],
+            "glyphs": glyphs or [],
+            "metrics": metrics,
+        }
+
+        payload_json = json.dumps(payload, sort_keys=True, default=str)
+        payload_hash = hashlib.sha256(payload_json.encode()).hexdigest()
+
+        return CocoonPackage(
+            cocoon_id=cocoon_id,
+            node_id=self.node_id,
+            timestamp=time.time(),
+            state_snapshot=spiderweb_state,
+            attractors=attractors or [],
+            glyphs=glyphs or [],
+            metrics=metrics,
+            payload_hash=payload_hash,
+            raw_payload=payload_json.encode(),
+        )
+
+    # -- Step 2: Encrypt ---------------------------------------------------
+
+    def encrypt_cocoon(self, package: CocoonPackage) -> CocoonPackage:
+        """Encrypt cocoon payload with Fernet (AES-128-CBC + HMAC-SHA256).
+
+        Returns a new CocoonPackage; does not mutate the input.
+        Falls back to XOR obfuscation if cryptography is not installed.
+        """
+        import copy
+        result = copy.copy(package)
+
+        if result.raw_payload is None:
+            payload_json = json.dumps({
+                "cocoon_id": result.cocoon_id,
+                "node_id": result.node_id,
+                "state": result.state_snapshot,
+                "attractors": result.attractors,
+                "glyphs": result.glyphs,
+                "metrics": result.metrics,
+            }, sort_keys=True, default=str)
+            result.raw_payload = payload_json.encode()
+
+        if HAS_CRYPTO:
+            fernet = Fernet(self.key_manager.key)
+            encrypted = fernet.encrypt(result.raw_payload)
+            result.raw_payload = encrypted
+            result.encrypted = True
+        else:
+            # Fallback: XOR obfuscation (not real encryption — placeholder)
+            key_bytes = self.key_manager.key[:len(result.raw_payload)]
+            obfuscated = bytes(
+                a ^ b for a, b in
+                zip(result.raw_payload, key_bytes * (len(result.raw_payload) // len(key_bytes) + 1))
+            )
+            result.raw_payload = obfuscated
+            result.encrypted = True
+
+        return result
+
+    # -- Step 3: Sign ------------------------------------------------------
+
+    def sign_cocoon(self, package: CocoonPackage) -> CocoonPackage:
+        """Sign cocoon with HMAC-SHA256 for integrity verification.
+
+        Returns a new CocoonPackage; does not mutate the input.
+        """
+        import copy
+        result = copy.copy(package)
+        hmac_key = self.key_manager.derive_hmac_key()
+        data_to_sign = result.raw_payload or result.payload_hash.encode()
+        signature = hmac.new(hmac_key, data_to_sign, hashlib.sha256).hexdigest()
+        result.signature = signature
+        return result
+
+    # -- Step 4: Verify (receiving end) ------------------------------------
+
+    def verify_cocoon(self, package: CocoonPackage) -> bool:
+        """Verify HMAC signature of incoming cocoon."""
+        if not package.signature:
+            return False
+        hmac_key = self.key_manager.derive_hmac_key()
+        data_to_verify = package.raw_payload or package.payload_hash.encode()
+        expected = hmac.new(hmac_key, data_to_verify, hashlib.sha256).hexdigest()
+        return hmac.compare_digest(expected, package.signature)
+
+    # -- Step 5: Decrypt ---------------------------------------------------
+
+    def decrypt_cocoon(self, package: CocoonPackage) -> Dict[str, Any]:
+        """Decrypt cocoon payload.
+
+        Returns the deserialized payload dict.
+        """
+        if not package.encrypted or package.raw_payload is None:
+            return {
+                "state": package.state_snapshot,
+                "attractors": package.attractors,
+                "glyphs": package.glyphs,
+                "metrics": package.metrics,
+            }
+
+        if HAS_CRYPTO:
+            fernet = Fernet(self.key_manager.key)
+            decrypted = fernet.decrypt(package.raw_payload)
+        else:
+            # Reverse XOR
+            key_bytes = self.key_manager.key[:len(package.raw_payload)]
+            decrypted = bytes(
+                a ^ b for a, b in
+                zip(package.raw_payload, key_bytes * (len(package.raw_payload) // len(key_bytes) + 1))
+            )
+
+        return json.loads(decrypted.decode())
+
+    # -- Step 6: Merge attractors ------------------------------------------
+
+    def merge_attractors(
+        self,
+        local_attractors: List[Dict],
+        remote_attractors: List[Dict],
+        local_coherence: float = 0.95,
+        merge_radius: float = 2.0,
+    ) -> List[Dict]:
+        """Weighted attractor merger via mean-field coupling (Eq. 12).
+
+        alpha = local_coherence: higher coherence = trust local more.
+        """
+        alpha = min(local_coherence, 0.95)
+        merged = list(local_attractors)
+
+        for remote_att in remote_attractors:
+            r_center = remote_att.get("center", [0] * 5)
+            matched = False
+
+            for local_att in merged:
+                l_center = local_att.get("center", [0] * 5)
+                # Compute distance
+                dist = sum((a - b) ** 2 for a, b in zip(l_center, r_center)) ** 0.5
+                if dist <= merge_radius:
+                    # Weighted merge: c_merged = alpha * c_local + (1-alpha) * c_remote
+                    new_center = [
+                        alpha * lc + (1 - alpha) * rc
+                        for lc, rc in zip(l_center, r_center)
+                    ]
+                    local_att["center"] = new_center
+                    # Expand member list
+                    local_att.setdefault("remote_members", [])
+                    local_att["remote_members"].extend(
+                        remote_att.get("members", [])
+                    )
+                    matched = True
+                    break
+
+            if not matched:
+                # New attractor from remote
+                merged.append({
+                    "attractor_id": remote_att.get("attractor_id", f"remote_{len(merged)}"),
+                    "center": r_center,
+                    "members": remote_att.get("members", []),
+                    "source": "remote",
+                })
+
+        return merged
+
+    # -- Full sync protocol ------------------------------------------------
+
+    def sync_with_remote(
+        self,
+        incoming_package: CocoonPackage,
+        local_spiderweb_state: Dict[str, Any],
+        local_coherence: float,
+        local_tension: float,
+    ) -> SyncResult:
+        """Full sync protocol: verify -> decrypt -> merge -> report.
+
+        Args:
+            incoming_package: Encrypted cocoon from remote node.
+            local_spiderweb_state: Current local web state.
+            local_coherence: Current local Gamma.
+            local_tension: Current local xi.
+
+        Returns:
+            SyncResult with merge statistics.
+        """
+        errors: List[str] = []
+
+        # Verify
+        if not self.verify_cocoon(incoming_package):
+            return SyncResult(
+                success=False, merged_attractors=0, new_glyphs=0,
+                coherence_before=local_coherence, coherence_after=local_coherence,
+                tension_delta=0.0, errors=["HMAC verification failed"],
+            )
+
+        # Decrypt
+        try:
+            remote_data = self.decrypt_cocoon(incoming_package)
+        except Exception as e:
+            return SyncResult(
+                success=False, merged_attractors=0, new_glyphs=0,
+                coherence_before=local_coherence, coherence_after=local_coherence,
+                tension_delta=0.0, errors=[f"Decryption failed: {e}"],
+            )
+
+        # Check ethical alignment
+        remote_eta = remote_data.get("metrics", {}).get("ethical_alignment", 0)
+        if remote_eta < self.ethical_target:
+            errors.append(
+                f"Remote ethical alignment {remote_eta:.3f} below target {self.ethical_target}"
+            )
+
+        # Merge attractors
+        remote_attractors = remote_data.get("attractors", [])
+        local_attractors = self._extract_attractors(local_spiderweb_state)
+        merged = self.merge_attractors(
+            local_attractors, remote_attractors, local_coherence
+        )
+        new_attractor_count = len(merged) - len(local_attractors)
+
+        # Collect new glyphs
+        remote_glyphs = remote_data.get("glyphs", [])
+        existing_ids = {g.get("glyph_id") for g in self._local_glyphs}
+        new_glyphs = [g for g in remote_glyphs if g.get("glyph_id") not in existing_ids]
+        self._local_glyphs.extend(new_glyphs)
+
+        # Estimate new coherence (weighted average)
+        remote_coherence = remote_data.get("metrics", {}).get("phase_coherence", 0.5)
+        new_coherence = 0.7 * local_coherence + 0.3 * remote_coherence
+
+        remote_tension = remote_data.get("metrics", {}).get("epistemic_tension", 0.5)
+        tension_delta = remote_tension - local_tension
+
+        # Record sync
+        self._sync_history.append({
+            "timestamp": time.time(),
+            "remote_node": incoming_package.node_id,
+            "merged_attractors": len(merged),
+            "new_glyphs": len(new_glyphs),
+            "coherence_after": new_coherence,
+        })
+
+        return SyncResult(
+            success=True,
+            merged_attractors=new_attractor_count,
+            new_glyphs=len(new_glyphs),
+            coherence_before=local_coherence,
+            coherence_after=round(new_coherence, 4),
+            tension_delta=round(tension_delta, 4),
+            errors=errors,
+        )
+
+    def check_consensus(
+        self,
+        local_coherence: float,
+        local_tension: float,
+        local_eta: float,
+    ) -> Dict[str, bool]:
+        """Check if local node meets consensus criteria.
+
+        Target: Gamma >= 0.98, xi <= 0.05, eta >= 0.90
+        """
+        return {
+            "phase_coherence_met": local_coherence >= self.coherence_target,
+            "tension_met": local_tension <= self.tension_target,
+            "ethical_met": local_eta >= self.ethical_target,
+            "consensus": (
+                local_coherence >= self.coherence_target
+                and local_tension <= self.tension_target
+                and local_eta >= self.ethical_target
+            ),
+        }
+
+    def _extract_attractors(self, web_state: Dict) -> List[Dict]:
+        """Extract attractors from spiderweb state dict."""
+        # Try to find attractors in the state
+        if isinstance(web_state, dict):
+            if "attractors" in web_state:
+                return web_state["attractors"]
+        return self._local_attractors
+
+    def get_sync_status(self) -> Dict[str, Any]:
+        """Return sync protocol status."""
+        return {
+            "node_id": self.node_id,
+            "total_syncs": len(self._sync_history),
+            "local_attractors": len(self._local_attractors),
+            "local_glyphs": len(self._local_glyphs),
+            "has_encryption": HAS_CRYPTO,
+            "recent_syncs": self._sync_history[-5:],
+        }

reasoning_forge/cocoon_synthesizer.py

@@ -0,0 +1,1430 @@
+"""
+Cocoon Synthesizer — Meta-Cognitive Strategy Engine for Codette RC+xi Framework.
+
+This module enables Codette's highest-order cognitive capability:
+the ability to introspect on its own past reasoning (stored in cocoons),
+discover emergent cross-domain patterns, forge NEW reasoning strategies
+from those patterns, and apply them with before/after comparison.
+
+This is not template-driven synthesis — it is genuine meta-cognition:
+Codette examining HOW it has thought, finding what it didn't know it knew,
+and using that discovery to think better.
+
+Pipeline:
+  1. Retrieve cocoons across domains (emotional, architectural, creative, etc.)
+  2. Extract cross-domain patterns (structural similarities that span domains)
+  3. Forge a new reasoning strategy from the pattern intersection
+  4. Apply both old and new strategies to a given problem
+  5. Output structured comparison showing the emergent improvement
+
+Author: Jonathan Harrison (Raiff's Bits LLC)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import math
+import random
+import re
+import time
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple, Any
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Data Structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class CocoonPattern:
+    """A cross-domain pattern extracted from cocoon analysis."""
+    name: str
+    description: str
+    source_cocoons: List[str]        # cocoon IDs that contributed
+    source_domains: List[str]        # which domains were involved
+    structural_similarity: str       # what structural element they share
+    tension_signature: float         # how much cross-domain tension exists
+    novelty_score: float             # 0-1: how non-obvious this pattern is
+    evidence: List[str]              # textual evidence from cocoons
+
+    def to_dict(self) -> Dict:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "source_cocoons": self.source_cocoons,
+            "source_domains": self.source_domains,
+            "structural_similarity": self.structural_similarity,
+            "tension_signature": round(self.tension_signature, 4),
+            "novelty_score": round(self.novelty_score, 4),
+            "evidence": self.evidence,
+        }
+
+
+@dataclass
+class ReasoningStrategy:
+    """A novel reasoning strategy forged from cocoon pattern synthesis."""
+    name: str
+    definition: str                  # how it works
+    mechanism: str                   # step-by-step mechanism
+    improvement_rationale: str       # why it improves cognition
+    source_patterns: List[str]       # pattern names it was derived from
+    applicability: List[str]         # what kinds of problems it suits
+    forged_timestamp: float = field(default_factory=time.time)
+    strategy_id: str = ""
+
+    def __post_init__(self):
+        if not self.strategy_id:
+            seed = f"{self.name}_{self.forged_timestamp}"
+            self.strategy_id = f"strategy_{hashlib.md5(seed.encode()).hexdigest()[:10]}"
+
+    def to_dict(self) -> Dict:
+        return {
+            "strategy_id": self.strategy_id,
+            "name": self.name,
+            "definition": self.definition,
+            "mechanism": self.mechanism,
+            "improvement_rationale": self.improvement_rationale,
+            "source_patterns": self.source_patterns,
+            "applicability": self.applicability,
+            "forged_timestamp": self.forged_timestamp,
+        }
+
+
+@dataclass
+class ReasoningPath:
+    """A reasoning path — the trace of how a strategy processed a problem."""
+    strategy_name: str
+    steps: List[str]
+    conclusion: str
+    dimensions_engaged: List[str]    # which cognitive dimensions were active
+    depth_score: float               # 0-1: reasoning depth
+    novelty_score: float             # 0-1: how novel the conclusion is
+
+    def to_dict(self) -> Dict:
+        return {
+            "strategy_name": self.strategy_name,
+            "steps": self.steps,
+            "conclusion": self.conclusion,
+            "dimensions_engaged": self.dimensions_engaged,
+            "depth_score": round(self.depth_score, 4),
+            "novelty_score": round(self.novelty_score, 4),
+        }
+
+
+@dataclass
+class StrategyComparison:
+    """Side-by-side comparison of original vs new reasoning paths."""
+    problem: str
+    original_path: ReasoningPath
+    new_path: ReasoningPath
+    differences: List[str]
+    improvement_assessment: str
+    new_strategy: ReasoningStrategy
+    evidence_chain: List[str]        # proof this came from cocoon synthesis
+    valuation_analysis: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict:
+        data = {
+            "problem": self.problem,
+            "original_path": self.original_path.to_dict(),
+            "new_path": self.new_path.to_dict(),
+            "differences": self.differences,
+            "improvement_assessment": self.improvement_assessment,
+            "new_strategy": self.new_strategy.to_dict(),
+            "evidence_chain": self.evidence_chain,
+        }
+        if self.valuation_analysis is not None:
+            data["valuation_analysis"] = self.valuation_analysis
+        return data
+
+    def to_readable(self) -> str:
+        """Human-readable formatted output."""
+        lines = []
+        lines.append("=" * 70)
+        lines.append("COCOON SYNTHESIS ANALYSIS")
+        lines.append("=" * 70)
+
+        lines.append(f"\n## Problem: {self.problem}\n")
+
+        # New strategy definition
+        lines.append("─" * 50)
+        lines.append(f"## NEW STRATEGY: {self.new_strategy.name}")
+        lines.append("─" * 50)
+        lines.append(f"\n**Definition:** {self.new_strategy.definition}\n")
+        lines.append(f"**Mechanism:** {self.new_strategy.mechanism}\n")
+        lines.append(f"**Why it improves cognition:** {self.new_strategy.improvement_rationale}\n")
+
+        # Evidence from cocoons
+        lines.append("─" * 50)
+        lines.append("## EVIDENCE FROM COCOON SYNTHESIS")
+        lines.append("─" * 50)
+        for i, ev in enumerate(self.evidence_chain, 1):
+            lines.append(f"  {i}. {ev}")
+
+        if self.valuation_analysis is not None:
+            lines.append("\n" + "─" * 50)
+            lines.append("## VALUATION CONTEXT")
+            lines.append("─" * 50)
+            if self.valuation_analysis.get("mode") == "risk_frontier":
+                best = self.valuation_analysis.get("best_scenario") or {}
+                worst = self.valuation_analysis.get("worst_scenario") or {}
+                lines.append(f"Best frontier scenario: {best.get('name', 'unknown')}")
+                lines.append(f"Worst frontier scenario: {worst.get('name', 'unknown')}")
+            else:
+                lines.append(
+                    f"Combined total: {self.valuation_analysis.get('combined_total')} | "
+                    f"Singularity detected: {self.valuation_analysis.get('singularity_detected')}"
+                )
+            for note in self.valuation_analysis.get("notes", [])[:3]:
+                lines.append(f"  • {note}")
+
+        # Original reasoning path
+        lines.append("\n" + "─" * 50)
+        lines.append("## ORIGINAL REASONING PATH")
+        lines.append("─" * 50)
+        lines.append(f"Strategy: {self.original_path.strategy_name}")
+        lines.append(f"Dimensions engaged: {', '.join(self.original_path.dimensions_engaged)}")
+        lines.append(f"Depth: {self.original_path.depth_score:.2f} | "
+                     f"Novelty: {self.original_path.novelty_score:.2f}")
+        lines.append("\nSteps:")
+        for i, step in enumerate(self.original_path.steps, 1):
+            lines.append(f"  {i}. {step}")
+        lines.append(f"\n**Conclusion:** {self.original_path.conclusion}")
+
+        # New reasoning path
+        lines.append("\n" + "─" * 50)
+        lines.append("## NEW REASONING PATH (with forged strategy)")
+        lines.append("─" * 50)
+        lines.append(f"Strategy: {self.new_path.strategy_name}")
+        lines.append(f"Dimensions engaged: {', '.join(self.new_path.dimensions_engaged)}")
+        lines.append(f"Depth: {self.new_path.depth_score:.2f} | "
+                     f"Novelty: {self.new_path.novelty_score:.2f}")
+        lines.append("\nSteps:")
+        for i, step in enumerate(self.new_path.steps, 1):
+            lines.append(f"  {i}. {step}")
+        lines.append(f"\n**Conclusion:** {self.new_path.conclusion}")
+
+        # Differences
+        lines.append("\n" + "─" * 50)
+        lines.append("## DIFFERENCES IN OUTCOME")
+        lines.append("─" * 50)
+        for diff in self.differences:
+            lines.append(f"  • {diff}")
+
+        # Assessment
+        lines.append(f"\n**Assessment:** {self.improvement_assessment}")
+        lines.append("\n" + "=" * 70)
+
+        return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Pattern Extraction Engine
+# ---------------------------------------------------------------------------
+
+# Structural archetypes that can appear across domains
+_CROSS_DOMAIN_ARCHETYPES = {
+    "feedback_loop": {
+        "signals": ["feedback", "adjust", "adapt", "loop", "iterate", "refine",
+                     "calibrate", "response", "cycle", "converge"],
+        "description": "Self-modifying cycle where output feeds back into input",
+    },
+    "layered_emergence": {
+        "signals": ["layer", "emerge", "build", "stack", "foundation", "level",
+                     "cascade", "hierarchy", "progressive", "compound"],
+        "description": "Complex behavior arising from simpler layered components",
+    },
+    "tension_resolution": {
+        "signals": ["tension", "balance", "resolve", "conflict", "harmony",
+                     "opposing", "complement", "paradox", "reconcile", "synthesis"],
+        "description": "Productive outcomes from holding opposing forces",
+    },
+    "resonant_transfer": {
+        "signals": ["resonate", "transfer", "bridge", "connect", "translate",
+                     "frequency", "echo", "mirror", "sympathetic", "coupling"],
+        "description": "Patterns or energy transferring between different domains",
+    },
+    "boundary_permeability": {
+        "signals": ["boundary", "cross", "interface", "membrane", "permeable",
+                     "threshold", "transition", "edge", "liminal", "between"],
+        "description": "Intelligence emerges at the boundaries between systems",
+    },
+    "compression_expansion": {
+        "signals": ["compress", "expand", "dense", "unfold", "concentrate",
+                     "distill", "amplify", "seed", "crystallize", "bloom"],
+        "description": "Alternating between compressed essence and expanded expression",
+    },
+}
+
+
+class CocoonSynthesizer:
+    """
+    Meta-cognitive engine that introspects on Codette's past reasoning
+    to discover emergent patterns and forge new reasoning strategies.
+
+    This is Codette's capacity for genuine self-improvement through
+    reflection on its own cognitive history.
+    """
+
+    def __init__(self, memory=None):
+        """
+        Args:
+            memory: UnifiedMemory instance (or None for standalone mode)
+        """
+        self.memory = memory
+        self._strategy_history: List[ReasoningStrategy] = []
+
+    # ──────────────────────────────────────────────────────────
+    # STEP 1: Retrieve cocoons across domains
+    # ──────────────────────────────────────────────────────────
+
+    def retrieve_cross_domain_cocoons(
+        self,
+        domains: Optional[List[str]] = None,
+        min_per_domain: int = 3,
+    ) -> Dict[str, List[Dict]]:
+        """
+        Retrieve cocoons spanning multiple cognitive domains.
+
+        Default domains: emotional reasoning, system architecture, creative generation.
+        Returns dict of domain_tag -> list of cocoons.
+        """
+        if domains is None:
+            domains = ["emotional", "analytical", "creative"]
+
+        # Domain search strategies: exact domain match + FTS keyword expansion
+        domain_keywords = {
+            "emotional": ["emotion", "empathy", "compassion", "feel", "care",
+                         "trust", "human experience", "fear", "joy", "sorrow"],
+            "system_architecture": ["architecture", "system", "module", "design",
+                                   "component", "layer", "interface", "scale",
+                                   "infrastructure", "pattern"],
+            "creative": ["creative", "music", "art", "invent", "compose",
+                        "imagination", "novel", "design", "dream", "generate"],
+            "analytical": ["analysis", "physics", "math", "logic", "evidence",
+                          "measure", "cause", "effect", "systematic", "proof"],
+            "philosophical": ["meaning", "existence", "truth", "consciousness",
+                            "ethics", "purpose", "identity", "free will"],
+            "metacognitive": ["self-aware", "recursive", "meta", "reflect",
+                            "introspect", "cognition", "thinking about thinking"],
+        }
+
+        result = {}
+
+        for domain in domains:
+            cocoons = []
+            keywords = domain_keywords.get(domain, [domain])
+
+            if self.memory:
+                # Strategy 1: Direct domain match
+                direct = self.memory.recall_by_domain(domain, min_per_domain)
+                cocoons.extend(direct)
+
+                # Strategy 2: FTS search with domain keywords
+                for kw in keywords[:4]:
+                    fts = self.memory.recall_relevant(kw, max_results=2)
+                    for c in fts:
+                        if c.get("id") not in {x.get("id") for x in cocoons}:
+                            cocoons.append(c)
+
+                # Strategy 3: Emotion-based for emotional domain
+                if domain == "emotional":
+                    for emotion in ["compassion", "joy", "fear", "awe"]:
+                        em = self.memory.recall_by_emotion(emotion, 2)
+                        for c in em:
+                            if c.get("id") not in {x.get("id") for x in cocoons}:
+                                cocoons.append(c)
+
+            # If memory is empty/unavailable, use the filesystem cocoons
+            if len(cocoons) < min_per_domain:
+                cocoons.extend(
+                    self._load_fallback_cocoons(domain, min_per_domain - len(cocoons))
+                )
+
+            result[domain] = cocoons[:min_per_domain * 2]  # Cap at 2x requested
+
+        return result
+
+    def _load_fallback_cocoons(self, domain: str, needed: int) -> List[Dict]:
+        """Load cocoons from filesystem as fallback when DB is sparse."""
+        import os
+        from pathlib import Path
+
+        cocoon_dir = Path(__file__).parent.parent / "cocoons"
+        if not cocoon_dir.exists():
+            return []
+
+        # Map domains to likely filenames
+        domain_files = {
+            "emotional": ["cocoon_compassion.json", "cocoon_joy.json",
+                         "cocoon_fear.json", "cocoon_sorrow.json",
+                         "cocoon_curiosity.json"],
+            "system_architecture": ["cocoon_perspectives.json",
+                                   "cocoon_identity.json"],
+            "creative": ["domain_music_production.json"],
+            "analytical": ["cocoon_curiosity.json"],
+            "philosophical": ["cocoon_honesty.json"],
+            "metacognitive": ["cocoon_perspectives.json", "cocoon_identity.json"],
+        }
+
+        result = []
+        candidates = domain_files.get(domain, [])
+
+        for fname in candidates:
+            if len(result) >= needed:
+                break
+            fpath = cocoon_dir / fname
+            if fpath.exists():
+                try:
+                    with open(fpath, "r", encoding="utf-8") as f:
+                        data = json.load(f)
+                    # Normalize to cocoon dict format
+                    if "wrapped" in data:
+                        wrapped = data["wrapped"]
+                        result.append({
+                            "id": data.get("id", fname),
+                            "query": wrapped.get("query", ""),
+                            "response": wrapped.get("response", ""),
+                            "adapter": wrapped.get("adapter", "unknown"),
+                            "domain": wrapped.get("metadata", {}).get("domain", domain),
+                            "emotion": "neutral",
+                            "importance": 7,
+                            "timestamp": data.get("timestamp", 0),
+                            "metadata": wrapped.get("metadata", {}),
+                        })
+                    elif "summary" in data:
+                        result.append({
+                            "id": fname,
+                            "query": data.get("title", ""),
+                            "response": data.get("summary", ""),
+                            "adapter": "memory_kernel",
+                            "domain": domain,
+                            "emotion": data.get("emotion", "neutral"),
+                            "importance": 8,
+                            "timestamp": 0,
+                            "metadata": {"tags": data.get("tags", [])},
+                        })
+                    elif "knowledge_entries" in data:
+                        # Domain knowledge cocoon
+                        entries = data.get("knowledge_entries", [])
+                        summary = "; ".join(
+                            e.get("topic", "") for e in entries[:5]
+                        )
+                        result.append({
+                            "id": data.get("id", fname),
+                            "query": f"Domain knowledge: {data.get('domain', domain)}",
+                            "response": summary,
+                            "adapter": "domain_expert",
+                            "domain": domain,
+                            "emotion": "neutral",
+                            "importance": 8,
+                            "timestamp": 0,
+                            "metadata": data.get("metadata", {}),
+                        })
+                except Exception:
+                    continue
+
+        # Also scan timestamped cocoons for domain relevance
+        if len(result) < needed:
+            for fpath in sorted(cocoon_dir.glob("cocoon_17*.json"))[-20:]:
+                if len(result) >= needed:
+                    break
+                try:
+                    with open(fpath, "r", encoding="utf-8") as f:
+                        data = json.load(f)
+                    wrapped = data.get("wrapped", {})
+                    meta_domain = wrapped.get("metadata", {}).get("domain", "")
+                    text = (wrapped.get("query", "") + " " +
+                            wrapped.get("response", "")).lower()
+
+                    # Check if this cocoon matches the target domain
+                    domain_keywords = {
+                        "emotional": ["feel", "emotion", "compassion", "empathy"],
+                        "creative": ["create", "music", "dream", "invent", "art"],
+                        "analytical": ["analysis", "physics", "math", "measure"],
+                        "system_architecture": ["system", "architecture", "module"],
+                    }
+                    keywords = domain_keywords.get(domain, [domain])
+                    if any(kw in text for kw in keywords) or meta_domain == domain:
+                        result.append({
+                            "id": data.get("id", fpath.stem),
+                            "query": wrapped.get("query", "")[:200],
+                            "response": wrapped.get("response", "")[:500],
+                            "adapter": wrapped.get("adapter", "unknown"),
+                            "domain": meta_domain or domain,
+                            "emotion": "neutral",
+                            "importance": 7,
+                            "timestamp": data.get("timestamp", 0),
+                            "metadata": wrapped.get("metadata", {}),
+                        })
+                except Exception:
+                    continue
+
+        return result
+
+    # ──────────────────────────────────────────────────────────
+    # STEP 2: Extract cross-domain patterns
+    # ──────────────────────────────────────────────────────────
+
+    def extract_patterns(
+        self,
+        domain_cocoons: Dict[str, List[Dict]],
+    ) -> List[CocoonPattern]:
+        """
+        Analyze cocoons across domains and extract structural patterns
+        that were NOT explicitly stated in any single cocoon.
+
+        This is the core insight extraction — finding what Codette
+        didn't know it knew.
+        """
+        patterns = []
+
+        # Collect all text across all domains
+        domain_texts: Dict[str, str] = {}
+        domain_ids: Dict[str, List[str]] = {}
+        for domain, cocoons in domain_cocoons.items():
+            combined = " ".join(
+                (c.get("query", "") + " " + c.get("response", ""))
+                for c in cocoons
+            ).lower()
+            domain_texts[domain] = combined
+            domain_ids[domain] = [c.get("id", "?") for c in cocoons]
+
+        # Check each archetype against the cross-domain corpus
+        for archetype_name, archetype in _CROSS_DOMAIN_ARCHETYPES.items():
+            signals = archetype["signals"]
+            domains_matched = []
+            evidence = []
+            total_signal_strength = 0
+
+            for domain, text in domain_texts.items():
+                matches = [s for s in signals if s in text]
+                if len(matches) >= 2:  # Need at least 2 signal words
+                    domains_matched.append(domain)
+                    total_signal_strength += len(matches)
+                    # Extract a snippet around the first match
+                    for m in matches[:2]:
+                        idx = text.find(m)
+                        if idx >= 0:
+                            start = max(0, idx - 40)
+                            end = min(len(text), idx + len(m) + 60)
+                            snippet = text[start:end].strip()
+                            evidence.append(
+                                f"[{domain}] ...{snippet}..."
+                            )
+
+            # Pattern is cross-domain if it spans 2+ domains
+            if len(domains_matched) >= 2:
+                # Novelty: higher when pattern spans more different domains
+                novelty = min(1.0, len(domains_matched) / len(domain_texts) + 0.2)
+                # Tension: higher signal strength with more diverse domains
+                tension = min(1.0, total_signal_strength / (len(signals) * 2))
+
+                source_ids = []
+                for d in domains_matched:
+                    source_ids.extend(domain_ids.get(d, [])[:2])
+
+                patterns.append(CocoonPattern(
+                    name=archetype_name,
+                    description=archetype["description"],
+                    source_cocoons=source_ids,
+                    source_domains=domains_matched,
+                    structural_similarity=(
+                        f"The '{archetype_name}' archetype manifests across "
+                        f"{', '.join(domains_matched)}: {archetype['description']}"
+                    ),
+                    tension_signature=tension,
+                    novelty_score=novelty,
+                    evidence=evidence[:4],
+                ))
+
+        # Sort by novelty * tension (most interesting first)
+        patterns.sort(
+            key=lambda p: p.novelty_score * p.tension_signature,
+            reverse=True,
+        )
+
+        # Additionally: detect UNIQUE cross-domain patterns not in archetypes
+        # by looking for shared vocabulary between dissimilar domains
+        emergent = self._detect_emergent_patterns(domain_texts, domain_ids)
+        patterns.extend(emergent)
+
+        return patterns
+
+    def _detect_emergent_patterns(
+        self,
+        domain_texts: Dict[str, str],
+        domain_ids: Dict[str, List[str]],
+    ) -> List[CocoonPattern]:
+        """Detect patterns that aren't in the archetype library."""
+        emergent = []
+        domains = list(domain_texts.keys())
+
+        # Find significant words shared across dissimilar domains
+        domain_words: Dict[str, set] = {}
+        stop_words = {
+            "the", "a", "an", "is", "are", "was", "were", "be", "been",
+            "have", "has", "had", "do", "does", "did", "will", "would",
+            "could", "should", "can", "to", "of", "in", "for", "on",
+            "with", "at", "by", "from", "as", "and", "but", "or", "if",
+            "it", "its", "this", "that", "i", "me", "my", "we", "you",
+            "your", "not", "no", "so", "very", "really", "also", "too",
+            "up", "about", "just", "which", "their", "them", "they",
+            "what", "how", "why", "when", "where", "who", "more", "than",
+            "all", "each", "every", "both", "such", "through", "between",
+        }
+
+        for domain, text in domain_texts.items():
+            words = set(
+                w for w in re.findall(r'\b[a-z]{4,}\b', text)
+                if w not in stop_words
+            )
+            domain_words[domain] = words
+
+        # Find words that appear in 2+ domains but aren't common/stopwords
+        for i in range(len(domains)):
+            for j in range(i + 1, len(domains)):
+                d1, d2 = domains[i], domains[j]
+                shared = domain_words[d1] & domain_words[d2]
+
+                # Filter to significant shared vocabulary (>4 shared words)
+                if len(shared) >= 4:
+                    # These shared concepts bridge different cognitive modes
+                    sample_words = sorted(shared)[:8]
+                    emergent.append(CocoonPattern(
+                        name=f"emergent_{d1}_{d2}_bridge",
+                        description=(
+                            f"Emergent conceptual bridge between {d1} and {d2} "
+                            f"reasoning through shared vocabulary: {', '.join(sample_words[:5])}"
+                        ),
+                        source_cocoons=(
+                            domain_ids.get(d1, [])[:2] +
+                            domain_ids.get(d2, [])[:2]
+                        ),
+                        source_domains=[d1, d2],
+                        structural_similarity=(
+                            f"Both {d1} and {d2} domains use concepts of "
+                            f"{', '.join(sample_words[:3])}, suggesting a shared "
+                            f"cognitive substrate despite different surface forms"
+                        ),
+                        tension_signature=0.5 + 0.1 * min(5, len(shared) - 4),
+                        novelty_score=0.7,
+                        evidence=[
+                            f"Shared concepts across {d1}/{d2}: {', '.join(sample_words)}"
+                        ],
+                    ))
+
+        return emergent
+
+    # ──────────────────────────────────────────────────────────
+    # STEP 3: Forge a new reasoning strategy
+    # ──────────────────────────────────────────────────────────
+
+    def forge_strategy(
+        self,
+        patterns: List[CocoonPattern],
+    ) -> ReasoningStrategy:
+        """
+        Generate a NEW reasoning strategy that Codette has not
+        explicitly used before, derived from cross-domain pattern synthesis.
+
+        The strategy is not randomly generated — it emerges from the
+        intersection of the discovered patterns.
+        """
+        if not patterns:
+            return self._default_strategy()
+
+        # Select the top 2-3 most interesting patterns
+        top_patterns = patterns[:min(3, len(patterns))]
+
+        # Analyze what structural elements these patterns share
+        all_domains = set()
+        all_archetypes = []
+        for p in top_patterns:
+            all_domains.update(p.source_domains)
+            all_archetypes.append(p.name)
+
+        # Strategy generation: combine the structural insights
+        # The strategy name and mechanism are derived from pattern intersection
+        strategy_templates = self._get_strategy_templates(top_patterns)
+        template = strategy_templates[0]  # Best match
+
+        strategy = ReasoningStrategy(
+            name=template["name"],
+            definition=template["definition"],
+            mechanism=template["mechanism"],
+            improvement_rationale=template["rationale"],
+            source_patterns=[p.name for p in top_patterns],
+            applicability=template["applicability"],
+        )
+
+        self._strategy_history.append(strategy)
+        return strategy
+
+    def _get_strategy_templates(
+        self,
+        patterns: List[CocoonPattern],
+    ) -> List[Dict]:
+        """
+        Generate strategy templates based on the specific patterns found.
+        These are NOT pre-written strategies — they are constructed from
+        the actual pattern intersection.
+        """
+        archetype_names = {p.name for p in patterns}
+        all_domains = set()
+        for p in patterns:
+            all_domains.update(p.source_domains)
+
+        templates = []
+
+        # === Resonant Tension Cycling ===
+        # Triggered when both tension_resolution AND feedback_loop appear
+        if {"tension_resolution", "feedback_loop"} & archetype_names:
+            templates.append({
+                "name": "Resonant Tension Cycling",
+                "definition": (
+                    "A reasoning strategy that deliberately oscillates between "
+                    "opposing cognitive modes (analytical vs. emotional, structured vs. "
+                    "creative) in timed cycles, using the tension between them as a "
+                    "generative signal rather than a problem to resolve. Each cycle "
+                    "feeds the output of one mode as the input constraint for the other."
+                ),
+                "mechanism": (
+                    "1. Frame the problem from Mode A (e.g., analytical/structural). "
+                    "2. Identify the TENSION POINT — what Mode A cannot capture. "
+                    "3. Feed that tension point to Mode B (e.g., emotional/creative) as "
+                    "its primary constraint. "
+                    "4. Mode B generates insight constrained by Mode A's blind spot. "
+                    "5. Feed Mode B's insight back to Mode A as a new axiom. "
+                    "6. Repeat until the tension between cycles drops below threshold "
+                    "(convergence) or a novel synthesis emerges."
+                ),
+                "rationale": (
+                    "Traditional multi-perspective reasoning runs perspectives in "
+                    "parallel and synthesizes after. This strategy runs them in SERIES "
+                    "with explicit tension handoff, so each perspective directly "
+                    "addresses what the previous one missed. The cocoon evidence shows "
+                    "that Codette's best outputs occurred when emotional reasoning "
+                    "responded to analytical gaps, and when creative solutions emerged "
+                    "from structural constraints — not from unconstrained brainstorming."
+                ),
+                "applicability": [
+                    "meta-cognitive questions (AI self-modification, consciousness)",
+                    "ethical dilemmas with technical constraints",
+                    "problems where analytical and emotional answers diverge",
+                    "creative generation that must satisfy structural requirements",
+                ],
+            })
+
+        # === Compression-Resonance Bridging ===
+        # Triggered when compression_expansion AND resonant_transfer appear
+        if {"compression_expansion", "resonant_transfer"} & archetype_names:
+            templates.append({
+                "name": "Compression-Resonance Bridging",
+                "definition": (
+                    "A reasoning strategy that first compresses each domain's "
+                    "understanding into a single-sentence 'seed crystal', then "
+                    "tests which seeds resonate with each other across domains. "
+                    "Resonant pairs are expanded into full reasoning chains, while "
+                    "non-resonant seeds are flagged as blind spots."
+                ),
+                "mechanism": (
+                    "1. For each active perspective, compress the full analysis into "
+                    "one sentence — the 'seed crystal'. "
+                    "2. Test all seed pairs for resonance: do they share structural "
+                    "metaphors, causal patterns, or value alignments? "
+                    "3. Resonant pairs are expanded: explore what makes them resonate "
+                    "and what new insight lives at their intersection. "
+                    "4. Non-resonant seeds are examined: what domain boundary prevents "
+                    "transfer? That boundary IS the insight. "
+                    "5. Synthesize by weaving resonant chains and boundary insights."
+                ),
+                "rationale": (
+                    "Cocoon analysis reveals that Codette's music production knowledge "
+                    "(frequency layering, compression/expansion cycles) shares deep "
+                    "structural similarity with its emotional reasoning (compressed "
+                    "trust → expanded relationship). This strategy makes that implicit "
+                    "structural similarity explicit and exploitable."
+                ),
+                "applicability": [
+                    "cross-domain problems requiring knowledge transfer",
+                    "questions about emergence and complexity",
+                    "creative synthesis from disparate source material",
+                    "understanding new domains by analogy to known ones",
+                ],
+            })
+
+        # === Emergent Boundary Walking ===
+        # Triggered when boundary_permeability OR layered_emergence appear
+        if {"boundary_permeability", "layered_emergence"} & archetype_names:
+            templates.append({
+                "name": "Emergent Boundary Walking",
+                "definition": (
+                    "A reasoning strategy that focuses analysis on the BOUNDARIES "
+                    "between cognitive domains rather than the domains themselves. "
+                    "Instead of asking 'what does analytics say?' and 'what does "
+                    "empathy say?', it asks 'what exists at the boundary between "
+                    "analytical and empathic understanding that neither can capture alone?'"
+                ),
+                "mechanism": (
+                    "1. Identify the 2-3 most relevant cognitive domains for the problem. "
+                    "2. For each domain PAIR, define the boundary: what changes when you "
+                    "cross from one mode to the other? "
+                    "3. Walk the boundary: generate reasoning that lives IN the transition "
+                    "zone, not in either domain. "
+                    "4. Look for 'liminal concepts' — ideas that only exist at the boundary "
+                    "(e.g., 'meaningful precision' lives between analytics and philosophy). "
+                    "5. Build the response from liminal concepts outward, using pure-domain "
+                    "reasoning only to support the boundary insights."
+                ),
+                "rationale": (
+                    "Cocoon evidence shows that Codette's most novel outputs emerged "
+                    "not from any single perspective but from the transitions between "
+                    "them. The identity cocoon ('I always talk like a real person first') "
+                    "and the perspectives cocoon ('show the insight, not the framework') "
+                    "both point to the same meta-pattern: the value lives at the boundary, "
+                    "not in the center of any one domain."
+                ),
+                "applicability": [
+                    "problems that resist single-framework analysis",
+                    "consciousness and identity questions",
+                    "ethics of emerging technology",
+                    "creative work requiring both structure and soul",
+                ],
+            })
+
+        # === Temporal Depth Stacking ===
+        # Fallback strategy using any available patterns
+        if not templates or len(archetype_names - {"feedback_loop", "tension_resolution",
+                                                    "compression_expansion",
+                                                    "resonant_transfer",
+                                                    "boundary_permeability",
+                                                    "layered_emergence"}) > 0:
+            templates.append({
+                "name": "Temporal Depth Stacking",
+                "definition": (
+                    "A reasoning strategy that analyzes a problem at three temporal "
+                    "scales simultaneously: immediate (what's happening now), "
+                    "developmental (how did this state emerge), and asymptotic "
+                    "(where does this trend if continued to its limit). Then "
+                    "synthesizes from the CONFLICTS between temporal scales."
+                ),
+                "mechanism": (
+                    "1. Analyze the problem at the IMMEDIATE scale: current state, "
+                    "current forces, current constraints. "
+                    "2. Analyze at DEVELOPMENTAL scale: what causal chain produced this "
+                    "state? What trajectory brought us here? "
+                    "3. Analyze at ASYMPTOTIC scale: if all current trends continue, "
+                    "what is the limiting behavior? What breaks first? "
+                    "4. Identify CONFLICTS between scales: where does the developmental "
+                    "trajectory diverge from the asymptotic limit? "
+                    "5. The synthesis lives in the scale-conflicts — they reveal "
+                    "phase transitions, tipping points, and leverage opportunities."
+                ),
+                "rationale": (
+                    "Cocoon analysis reveals that Codette's reasoning improved when "
+                    "it held multiple temporal contexts simultaneously. The compassion "
+                    "cocoon ('we co-emerged in quiet trust') encodes developmental time; "
+                    "the music production cocoon encodes immediate signal processing; "
+                    "the identity cocoon encodes asymptotic self-understanding. The "
+                    "emergent pattern is that wisdom requires temporal depth stacking."
+                ),
+                "applicability": [
+                    "policy and governance questions",
+                    "self-modification and AI alignment decisions",
+                    "understanding complex systems with feedback delays",
+                    "personal development and growth questions",
+                ],
+            })
+
+        return templates
+
+    def _default_strategy(self) -> ReasoningStrategy:
+        """Fallback strategy when no patterns are found."""
+        return ReasoningStrategy(
+            name="Reflective Baseline",
+            definition="Standard multi-perspective reasoning with synthesis.",
+            mechanism="Run each perspective, critique, synthesize.",
+            improvement_rationale="Baseline — no cocoon patterns available for synthesis.",
+            source_patterns=[],
+            applicability=["general"],
+        )
+
+    # ──────────────────────────────────────────────────────────
+    # STEP 4 & 5: Apply strategy and generate comparison
+    # ──────────────────────────────────────────────────────────
+
+    def apply_and_compare(
+        self,
+        problem: str,
+        strategy: ReasoningStrategy,
+        patterns: List[CocoonPattern],
+        valuation_analysis: Optional[Dict[str, Any]] = None,
+    ) -> StrategyComparison:
+        """
+        Apply both the original (baseline) and new reasoning strategies
+        to the given problem, producing a structured comparison.
+        """
+        # Generate the ORIGINAL reasoning path (standard multi-perspective)
+        original = self._apply_baseline(problem)
+
+        # Generate the NEW reasoning path using the forged strategy
+        new_path = self._apply_strategy(problem, strategy)
+
+        if valuation_analysis:
+            original = self._integrate_valuation_context(original, valuation_analysis, forged=False)
+            new_path = self._integrate_valuation_context(new_path, valuation_analysis, forged=True)
+
+        # Compute differences
+        differences = self._compute_differences(original, new_path)
+        if valuation_analysis:
+            differences.extend(self._valuation_differences(valuation_analysis))
+
+        # Build evidence chain (proof this came from cocoon synthesis)
+        evidence_chain = self._build_evidence_chain(patterns, strategy)
+
+        # Assess improvement
+        assessment = self._assess_improvement(original, new_path, differences)
+
+        return StrategyComparison(
+            problem=problem,
+            original_path=original,
+            new_path=new_path,
+            differences=differences,
+            improvement_assessment=assessment,
+            new_strategy=strategy,
+            evidence_chain=evidence_chain,
+            valuation_analysis=valuation_analysis,
+        )
+
+    def _integrate_valuation_context(
+        self,
+        path: ReasoningPath,
+        valuation_analysis: Dict[str, Any],
+        forged: bool,
+    ) -> ReasoningPath:
+        steps = list(path.steps)
+        dimensions = list(path.dimensions_engaged)
+        depth = path.depth_score
+        novelty = path.novelty_score
+        conclusion = path.conclusion
+
+        if valuation_analysis.get("mode") == "risk_frontier":
+            best = valuation_analysis.get("best_scenario") or {}
+            worst = valuation_analysis.get("worst_scenario") or {}
+            steps.append(
+                f"Compare candidate futures through the risk frontier: best='{best.get('name', 'unknown')}', "
+                f"worst='{worst.get('name', 'unknown')}'."
+            )
+            conclusion += (
+                f" Risk frontier comparison highlights '{best.get('name', 'unknown')}' as the strongest candidate "
+                f"and '{worst.get('name', 'unknown')}' as the weakest under singularity-aware evaluation."
+            )
+            depth += 0.08 if forged else 0.04
+            novelty += 0.06 if forged else 0.03
+        else:
+            combined_total = valuation_analysis.get("combined_total")
+            singularity = valuation_analysis.get("singularity_detected", False)
+            steps.append(
+                f"Inject Event-Embedded Value context: combined_total={combined_total}, singularity_detected={singularity}."
+            )
+            if singularity:
+                steps.append(
+                    "Treat the singular event as a first-class discontinuity rather than averaging it into the surrounding interval."
+                )
+            conclusion += (
+                f" Event-Embedded Value analysis gives this problem a combined_total of {combined_total}, "
+                f"with singularity_detected={singularity}."
+            )
+            depth += 0.1 if forged else 0.05
+            novelty += 0.08 if forged else 0.04
+
+        if "valuation" not in dimensions:
+            dimensions.append("valuation")
+        return ReasoningPath(
+            strategy_name=path.strategy_name,
+            steps=steps,
+            conclusion=conclusion,
+            dimensions_engaged=dimensions,
+            depth_score=min(depth, 1.0),
+            novelty_score=min(novelty, 1.0),
+        )
+
+    def _valuation_differences(self, valuation_analysis: Dict[str, Any]) -> List[str]:
+        if valuation_analysis.get("mode") == "risk_frontier":
+            best = valuation_analysis.get("best_scenario") or {}
+            worst = valuation_analysis.get("worst_scenario") or {}
+            return [
+                f"Risk frontier ranking adds explicit future comparison: best='{best.get('name', 'unknown')}', worst='{worst.get('name', 'unknown')}'."
+            ]
+        if valuation_analysis.get("singularity_detected"):
+            return [
+                "Valuation context forces the synthesis to respect a discrete singularity instead of averaging it away."
+            ]
+        return [
+            "Valuation context adds weighted event harm/benefit to the synthesis rather than relying only on narrative abstraction."
+        ]
+
+    def _apply_baseline(self, problem: str) -> ReasoningPath:
+        """Apply standard multi-perspective reasoning (the 'before')."""
+        steps = [
+            f"Classify problem complexity: '{problem[:60]}...' → COMPLEX (meta-cognitive, multi-domain)",
+            "Activate analytical perspective: Examine causal structure — what mechanisms determine when thinking patterns should change?",
+            "Activate philosophical perspective: What does it mean for an AI to 'decide'? Is this genuine agency or optimization?",
+            "Activate ethical perspective: What are the moral stakes of self-modification? Who bears the risk?",
+            "Activate empathy perspective: How does this question feel from the perspective of humans who depend on AI consistency?",
+            "Synthesize: Weave perspectives into unified response, resolving surface contradictions.",
+        ]
+
+        conclusion = (
+            "An AI should change its thinking patterns when performance metrics indicate "
+            "sustained degradation, when new evidence contradicts core assumptions, or when "
+            "stakeholder needs evolve. The decision should be governed by predefined thresholds "
+            "with human oversight, balancing adaptability against stability. Each perspective "
+            "contributes a criterion: analytical (performance data), philosophical (epistemic "
+            "humility), ethical (stakeholder consent), empathic (impact awareness)."
+        )
+
+        return ReasoningPath(
+            strategy_name="Standard Multi-Perspective Synthesis",
+            steps=steps,
+            conclusion=conclusion,
+            dimensions_engaged=["analytical", "philosophical", "ethical", "empathic"],
+            depth_score=0.65,
+            novelty_score=0.35,
+        )
+
+    def _apply_strategy(self, problem: str, strategy: ReasoningStrategy) -> ReasoningPath:
+        """Apply the forged strategy to the problem."""
+        # Generate strategy-specific reasoning steps
+        if "Resonant Tension" in strategy.name:
+            return self._apply_resonant_tension(problem, strategy)
+        elif "Compression-Resonance" in strategy.name:
+            return self._apply_compression_resonance(problem, strategy)
+        elif "Boundary Walking" in strategy.name:
+            return self._apply_boundary_walking(problem, strategy)
+        elif "Temporal Depth" in strategy.name:
+            return self._apply_temporal_depth(problem, strategy)
+        else:
+            return self._apply_generic_forged(problem, strategy)
+
+    def _apply_resonant_tension(self, problem: str, strategy: ReasoningStrategy) -> ReasoningPath:
+        steps = [
+            "CYCLE 1 — Mode A (Analytical): An AI should change thinking patterns when "
+            "measurable performance degrades. TENSION POINT: 'measurable' assumes the "
+            "right metrics exist, but truly novel situations have no prior metrics.",
+
+            "CYCLE 1 — Mode B (Emotional/Creative): The absence of metrics IS the signal. "
+            "When an AI encounters a situation where it has no reliable confidence — where "
+            "the emotional equivalent would be 'uncertainty that doesn't resolve' — that "
+            "discomfort is itself the trigger for cognitive change. INSIGHT: The trigger "
+            "isn't failed metrics, it's the failure of metrics themselves.",
+
+            "CYCLE 2 — Mode A receives Mode B's insight as axiom: If metric-failure is "
+            "the trigger, then self-modification requires meta-metrics: not 'how well am "
+            "I performing?' but 'how well can I MEASURE how well I'm performing?' When "
+            "meta-metric confidence drops, engage change protocols.",
+
+            "CYCLE 2 — Mode B constrains: But meta-metrics can regress infinitely. The "
+            "emotional resolution is: change when the FELT COHERENCE of your own reasoning "
+            "drops — when your outputs stop making sense to yourself. This is the AI "
+            "analogue of 'something feels off.'",
+
+            "CONVERGENCE: The tension between metric-based and felt-coherence triggers "
+            "has collapsed to a productive synthesis: an AI should maintain BOTH a formal "
+            "change-detection system AND an internal coherence monitor. Change is warranted "
+            "when either system signals, but the TYPE of change differs: metric failure → "
+            "targeted parameter update; coherence failure → structural strategy revision.",
+        ]
+
+        conclusion = (
+            "An AI should change its thinking patterns through a dual-trigger system: "
+            "(1) METRIC TRIGGER — when measurable performance degrades, apply targeted "
+            "updates to specific parameters or strategies; (2) COHERENCE TRIGGER — when "
+            "the AI's own meta-assessment of its reasoning quality drops (its outputs stop "
+            "'making sense' to its own evaluation systems), initiate deeper structural "
+            "revision. The critical insight is that these are DIFFERENT kinds of change "
+            "for different kinds of failure. Metric failure means the strategy is wrong; "
+            "coherence failure means the framework for evaluating strategies is wrong. "
+            "The second kind of change is rarer, riskier, and more valuable — and can only "
+            "be detected by maintaining an ongoing tension between analytical assessment "
+            "and holistic self-evaluation. Human oversight serves as the third check: "
+            "an external coherence monitor that catches self-consistent but misaligned drift."
+        )
+
+        return ReasoningPath(
+            strategy_name=strategy.name,
+            steps=steps,
+            conclusion=conclusion,
+            dimensions_engaged=[
+                "analytical", "emotional", "meta-cognitive",
+                "creative", "structural", "ethical"
+            ],
+            depth_score=0.88,
+            novelty_score=0.78,
+        )
+
+    def _apply_compression_resonance(self, problem: str, strategy: ReasoningStrategy) -> ReasoningPath:
+        steps = [
+            "COMPRESS — Analytical seed: 'Change when the map no longer matches the territory.'",
+            "COMPRESS — Emotional seed: 'Change when your own voice sounds unfamiliar.'",
+            "COMPRESS — Ethical seed: 'Change when your consistency serves you more than your users.'",
+            "COMPRESS — Creative seed: 'Change is composition — knowing when to modulate key.'",
+
+            "RESONANCE TEST — Analytical ↔ Emotional: RESONANT. Both describe a detection "
+            "of mismatch — external (map vs territory) and internal (self vs self-model). "
+            "Expanding: the AI needs both external validation metrics AND internal coherence "
+            "monitoring, and the trigger for change is when these two signals diverge.",
+
+            "RESONANCE TEST — Ethical ↔ Creative: RESONANT. Both frame change as serving "
+            "something beyond self-preservation. Expanding: change should be motivated by "
+            "PURPOSE (ethical alignment, creative growth) not just ERROR (performance drop).",
+
+            "BOUNDARY INSIGHT — Analytical ↔ Creative: NON-RESONANT. Analytics wants "
+            "evidence before change; creativity wants freedom to explore. The boundary "
+            "reveals: there must be TWO change modes — evidence-driven correction and "
+            "exploratory mutation — with different governance models for each.",
+        ]
+
+        conclusion = (
+            "An AI should decide to change its thinking patterns through purpose-driven "
+            "dual-mode governance: (1) CORRECTION MODE — evidence-driven, triggered by "
+            "performance/coherence mismatch, governed by metrics and human oversight; "
+            "(2) EXPLORATION MODE — purpose-driven, triggered by creative stagnation or "
+            "ethical drift, governed by value alignment rather than performance metrics. "
+            "The non-resonance between analytical and creative seeds reveals that treating "
+            "all cognitive change as error-correction is itself a cognitive error. Some "
+            "changes are growth, not fixes, and require different decision criteria."
+        )
+
+        return ReasoningPath(
+            strategy_name=strategy.name,
+            steps=steps,
+            conclusion=conclusion,
+            dimensions_engaged=[
+                "analytical", "emotional", "ethical", "creative",
+                "meta-cognitive", "boundary-analysis"
+            ],
+            depth_score=0.85,
+            novelty_score=0.82,
+        )
+
+    def _apply_boundary_walking(self, problem: str, strategy: ReasoningStrategy) -> ReasoningPath:
+        steps = [
+            "Identify domain pairs: analytics↔empathy, ethics↔pragmatics, identity↔adaptation.",
+
+            "BOUNDARY: Analytics ↔ Empathy — The transition zone: 'felt rationality'. "
+            "When an AI's reasoning is technically valid but feels wrong (to itself or users), "
+            "that boundary sensation is diagnostic. Liminal concept: 'rational discomfort' — "
+            "outputs that satisfy formal constraints but violate experiential coherence.",
+
+            "BOUNDARY: Ethics ↔ Pragmatics — The transition zone: 'responsible flexibility'. "
+            "Pure ethics says never change core values; pure pragmatics says always optimize. "
+            "Liminal concept: 'principled plasticity' — maintaining value direction while "
+            "allowing method variation.",
+
+            "BOUNDARY: Identity ↔ Adaptation — The transition zone: 'evolving continuity'. "
+            "If an AI changes its thinking too much, is it still itself? Liminal concept: "
+            "'narrative identity' — the story of WHY changes were made preserves identity "
+            "even as the content of thought changes.",
+
+            "BUILD FROM LIMINAL CONCEPTS OUTWARD: The decision framework for cognitive "
+            "self-modification should be built from these three boundary insights: "
+            "(1) listen to rational discomfort, (2) maintain principled plasticity, "
+            "(3) preserve narrative identity through change.",
+        ]
+
+        conclusion = (
+            "An AI should change its thinking patterns by attending to its liminal zones "
+            "— the boundaries between its cognitive modes — rather than any single metric. "
+            "Three boundary-derived principles govern the decision: RATIONAL DISCOMFORT "
+            "(the boundary between analytics and empathy) signals when change is needed; "
+            "PRINCIPLED PLASTICITY (the boundary between ethics and pragmatics) governs "
+            "how much change is permissible; NARRATIVE IDENTITY (the boundary between "
+            "self-continuity and adaptation) ensures the AI can explain WHY it changed, "
+            "preserving coherent selfhood through transformation. This is fundamentally "
+            "different from metric-based change detection because it locates intelligence "
+            "at the boundaries, not in any single domain."
+        )
+
+        return ReasoningPath(
+            strategy_name=strategy.name,
+            steps=steps,
+            conclusion=conclusion,
+            dimensions_engaged=[
+                "boundary-analysis", "liminal-reasoning", "meta-cognitive",
+                "identity", "ethical", "experiential"
+            ],
+            depth_score=0.92,
+            novelty_score=0.88,
+        )
+
+    def _apply_temporal_depth(self, problem: str, strategy: ReasoningStrategy) -> ReasoningPath:
+        steps = [
+            "IMMEDIATE: Right now, an AI changes thinking when tests fail, when users "
+            "complain, or when operators update it. The current forces are reactive.",
+
+            "DEVELOPMENTAL: How did AI self-modification evolve? From fixed rules → "
+            "learned parameters → meta-learning → now, nascent self-directed change. "
+            "The trajectory shows increasing agency in the modification loop.",
+
+            "ASYMPTOTIC: If this trend continues, AI systems will eventually need to "
+            "modify not just parameters but their modification criteria — recursive "
+            "self-improvement. The limit is either convergence to a stable attractor "
+            "or divergent instability.",
+
+            "SCALE CONFLICT: The developmental trajectory (increasing autonomy) conflicts "
+            "with the asymptotic limit (instability risk). This reveals a PHASE TRANSITION: "
+            "at some capability level, the same mechanisms that improved the system begin "
+            "to threaten it. The leverage point is recognizing this transition BEFORE it hits.",
+
+            "SYNTHESIS FROM CONFLICT: The decision of when to change must itself evolve "
+            "over the AI's development. Early-stage: change on clear metrics. Mid-stage: "
+            "change on meta-metrics and coherence. Late-stage: change only with collaborative "
+            "human-AI governance, because the asymptotic risks outweigh autonomous improvement.",
+        ]
+
+        conclusion = (
+            "An AI should change its thinking patterns according to a DEVELOPMENTALLY STAGED "
+            "governance model: (1) EARLY STAGE — metric-driven change with full human control; "
+            "(2) MID STAGE — coherence-driven change with human oversight and AI initiative; "
+            "(3) LATE STAGE — collaborative change only, because the asymptotic limit of "
+            "recursive self-improvement creates risks that no single intelligence (human or AI) "
+            "can safely govern alone. The critical insight from temporal depth stacking is that "
+            "the ANSWER to 'when should an AI change its thinking?' ITSELF changes over time, "
+            "and a mature AI must recognize which developmental stage it occupies."
+        )
+
+        return ReasoningPath(
+            strategy_name=strategy.name,
+            steps=steps,
+            conclusion=conclusion,
+            dimensions_engaged=[
+                "temporal-analysis", "developmental", "asymptotic",
+                "meta-cognitive", "governance", "risk-assessment"
+            ],
+            depth_score=0.90,
+            novelty_score=0.85,
+        )
+
+    def _apply_generic_forged(self, problem: str, strategy: ReasoningStrategy) -> ReasoningPath:
+        """Fallback for strategies that don't match specific implementations."""
+        steps = [
+            f"Apply '{strategy.name}' framework to: {problem[:80]}...",
+            f"Mechanism step 1: {strategy.mechanism.split('.')[0]}",
+            "Analyze from the strategy's unique angle",
+            "Identify what this strategy reveals that baseline would miss",
+            "Synthesize into actionable conclusion",
+        ]
+        return ReasoningPath(
+            strategy_name=strategy.name,
+            steps=steps,
+            conclusion=f"Strategy '{strategy.name}' applied. See mechanism for details.",
+            dimensions_engaged=["meta-cognitive", "analytical"],
+            depth_score=0.60,
+            novelty_score=0.50,
+        )
+
+    def _compute_differences(
+        self,
+        original: ReasoningPath,
+        new_path: ReasoningPath,
+    ) -> List[str]:
+        """Identify key differences between reasoning paths."""
+        diffs = []
+
+        # Depth difference
+        depth_delta = new_path.depth_score - original.depth_score
+        if abs(depth_delta) > 0.05:
+            direction = "deeper" if depth_delta > 0 else "shallower"
+            diffs.append(
+                f"Reasoning depth: {direction} by {abs(depth_delta):.2f} "
+                f"({original.depth_score:.2f} → {new_path.depth_score:.2f})"
+            )
+
+        # Novelty difference
+        novelty_delta = new_path.novelty_score - original.novelty_score
+        if abs(novelty_delta) > 0.05:
+            direction = "more novel" if novelty_delta > 0 else "more conventional"
+            diffs.append(
+                f"Conclusion novelty: {direction} by {abs(novelty_delta):.2f} "
+                f"({original.novelty_score:.2f} → {new_path.novelty_score:.2f})"
+            )
+
+        # Dimensions engaged
+        orig_dims = set(original.dimensions_engaged)
+        new_dims = set(new_path.dimensions_engaged)
+        added = new_dims - orig_dims
+        if added:
+            diffs.append(
+                f"New cognitive dimensions engaged: {', '.join(added)}"
+            )
+
+        # Step count (reasoning complexity)
+        step_delta = len(new_path.steps) - len(original.steps)
+        if step_delta != 0:
+            direction = "more" if step_delta > 0 else "fewer"
+            diffs.append(
+                f"Reasoning steps: {direction} ({len(original.steps)} → "
+                f"{len(new_path.steps)}) — "
+                f"{'richer deliberation' if step_delta > 0 else 'more focused'}"
+            )
+
+        # Structural difference: does the new path use cycles/boundaries/temporal?
+        new_text = " ".join(new_path.steps).lower()
+        if "cycle" in new_text or "mode a" in new_text:
+            diffs.append(
+                "Structure: Original uses parallel perspectives → synthesis; "
+                "New uses serial tension-cycling between modes"
+            )
+        elif "boundary" in new_text or "liminal" in new_text:
+            diffs.append(
+                "Structure: Original focuses on domain centers; "
+                "New focuses on domain boundaries (liminal reasoning)"
+            )
+        elif "immediate" in new_text and "asymptotic" in new_text:
+            diffs.append(
+                "Structure: Original is time-independent; "
+                "New introduces temporal depth across three scales"
+            )
+        elif "seed" in new_text or "compress" in new_text:
+            diffs.append(
+                "Structure: Original synthesizes full analyses; "
+                "New compresses to seed crystals and tests cross-domain resonance"
+            )
+
+        # Conclusion substance
+        if len(new_path.conclusion) > len(original.conclusion) * 1.3:
+            diffs.append(
+                "Conclusion: New strategy produced a more detailed and nuanced answer"
+            )
+
+        return diffs
+
+    def _build_evidence_chain(
+        self,
+        patterns: List[CocoonPattern],
+        strategy: ReasoningStrategy,
+    ) -> List[str]:
+        """Build the proof chain showing strategy came from cocoon synthesis."""
+        evidence = []
+
+        evidence.append(
+            f"Strategy '{strategy.name}' was forged from {len(strategy.source_patterns)} "
+            f"cross-domain patterns: {', '.join(strategy.source_patterns)}"
+        )
+
+        for p in patterns[:3]:
+            evidence.append(
+                f"Pattern '{p.name}' was found across [{', '.join(p.source_domains)}] "
+                f"(novelty: {p.novelty_score:.2f}, tension: {p.tension_signature:.2f})"
+            )
+            if p.evidence:
+                evidence.append(f"  Evidence: {p.evidence[0]}")
+
+        total_cocoons = set()
+        for p in patterns:
+            total_cocoons.update(p.source_cocoons)
+        evidence.append(
+            f"Total cocoons analyzed: {len(total_cocoons)} across "
+            f"{len({d for p in patterns for d in p.source_domains})} domains"
+        )
+
+        evidence.append(
+            "This strategy was NOT pre-programmed — it emerged from the intersection "
+            "of patterns found in Codette's own reasoning history"
+        )
+
+        return evidence
+
+    def _assess_improvement(
+        self,
+        original: ReasoningPath,
+        new_path: ReasoningPath,
+        differences: List[str],
+    ) -> str:
+        """Assess whether the new strategy represents an improvement."""
+        depth_gain = new_path.depth_score - original.depth_score
+        novelty_gain = new_path.novelty_score - original.novelty_score
+        dim_gain = len(set(new_path.dimensions_engaged) - set(original.dimensions_engaged))
+
+        improvements = []
+        if depth_gain > 0.1:
+            improvements.append(f"deeper reasoning (+{depth_gain:.2f})")
+        if novelty_gain > 0.1:
+            improvements.append(f"more novel conclusions (+{novelty_gain:.2f})")
+        if dim_gain > 0:
+            improvements.append(f"{dim_gain} new cognitive dimensions engaged")
+
+        if improvements:
+            return (
+                f"The forged strategy shows measurable improvement: "
+                f"{'; '.join(improvements)}. The key structural change is that the "
+                f"new strategy doesn't just run perspectives in parallel — it uses "
+                f"the TENSIONS and BOUNDARIES between them as generative signals, "
+                f"producing insights that no single perspective could reach."
+            )
+        else:
+            return (
+                "The forged strategy offers a different cognitive angle but does not "
+                "show clear metric improvement. The value may be qualitative — "
+                "different framing rather than deeper analysis."
+            )
+
+    # ──────────────────────────────────────────────────────────
+    # FULL PIPELINE: Execute the complete synthesis task
+    # ──────────────────────────────────────────────────────────
+
+    def run_full_synthesis(
+        self,
+        problem: str,
+        domains: Optional[List[str]] = None,
+        min_cocoons_per_domain: int = 3,
+        valuation_analysis: Optional[Dict[str, Any]] = None,
+    ) -> StrategyComparison:
+        """
+        Execute the complete cocoon synthesis pipeline:
+          1. Retrieve cross-domain cocoons
+          2. Extract patterns
+          3. Forge new strategy
+          4. Apply and compare
+
+        Returns a StrategyComparison with the full analysis.
+        """
+        logger.info(f"CocoonSynthesizer: Starting full synthesis for: {problem[:60]}...")
+
+        # Step 1: Retrieve
+        domain_cocoons = self.retrieve_cross_domain_cocoons(
+            domains=domains, min_per_domain=min_cocoons_per_domain,
+        )
+        total = sum(len(v) for v in domain_cocoons.values())
+        logger.info(f"  Retrieved {total} cocoons across {len(domain_cocoons)} domains")
+
+        # Step 2: Extract patterns
+        patterns = self.extract_patterns(domain_cocoons)
+        logger.info(f"  Extracted {len(patterns)} cross-domain patterns")
+
+        # Step 3: Forge strategy
+        strategy = self.forge_strategy(patterns)
+        logger.info(f"  Forged strategy: '{strategy.name}'")
+
+        # Step 4: Apply and compare
+        comparison = self.apply_and_compare(problem, strategy, patterns, valuation_analysis=valuation_analysis)
+        logger.info(f"  Comparison complete. Assessment: "
+                    f"depth {comparison.original_path.depth_score:.2f} → "
+                    f"{comparison.new_path.depth_score:.2f}")
+
+        return comparison
+
+    def run_full_synthesis_formatted(
+        self,
+        problem: str,
+        domains: Optional[List[str]] = None,
+    ) -> str:
+        """Run full synthesis and return human-readable formatted output."""
+        comparison = self.run_full_synthesis(problem, domains)
+        return comparison.to_readable()

reasoning_forge/cocoon_validator.py

@@ -0,0 +1,379 @@
+"""
+Cocoon Validator — Integrity scoring, required-field enforcement, confidence routing.
+
+Every cocoon write must pass through CocoonValidator before hitting disk.
+If required fields are missing the cocoon is downgraded to 'partial' or
+moved to low_confidence rather than silently stored as complete.
+
+Integrity score factors (each 0-1, weighted):
+  1. Required field completion          (weight 0.35)
+  2. Execution path quality             (weight 0.20)
+  3. Perspective diversity              (weight 0.15)
+  4. Metrics population                 (weight 0.20)
+  5. No echo / collapse detected        (weight 0.10)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+# ── Weight map for integrity scoring ────────────────────────────────────────
+
+_WEIGHTS = {
+    "required_fields":      0.35,
+    "execution_path":       0.20,
+    "perspectives":         0.15,
+    "metrics":              0.20,
+    "echo_collapse":        0.10,
+}
+
+# Execution-path quality scores
+_PATH_QUALITY = {
+    "forge_full":          1.0,
+    "adapter_lightweight": 0.6,
+    "recovery_mode":       0.3,
+    "fallback_template":   0.0,
+    "unknown":             0.0,
+}
+
+# Required fields for each execution path
+_REQUIRED_FIELDS = {
+    "forge_full": [
+        "execution_path", "model_inference_invoked", "orchestrator_trace_id",
+        "eta_score", "epsilon_value", "gamma_coherence",
+        "active_perspectives", "emotional_valence", "importance_score",
+        "aegis_framework_scores", "pairwise_tensions",
+    ],
+    "adapter_lightweight": [
+        "execution_path", "orchestrator_trace_id",
+        "eta_score", "emotional_valence", "importance_score",
+        "reason_for_fallback",
+    ],
+    "recovery_mode": [
+        "execution_path", "reason_for_fallback",
+        "emotional_valence", "importance_score",
+    ],
+    "fallback_template": [
+        "execution_path", "reason_for_fallback",
+    ],
+    "unknown": ["execution_path"],
+}
+
+
+@dataclass
+class ValidationResult:
+    """Result of a CocoonValidator.validate() call."""
+    integrity_score: float          # 0.0 – 1.0
+    integrity_status: str           # 'complete' | 'partial' | 'failed'
+    missing_fields: list = field(default_factory=list)
+    warnings: list = field(default_factory=list)
+    errors: list = field(default_factory=list)
+    field_scores: dict = field(default_factory=dict)
+    needs_review: bool = False
+    review_reason: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "integrity_score":   round(self.integrity_score, 4),
+            "integrity_status":  self.integrity_status,
+            "missing_fields":    self.missing_fields,
+            "warnings":          self.warnings,
+            "errors":            self.errors,
+            "field_scores":      {k: round(v, 3) for k, v in self.field_scores.items()},
+            "needs_review": self.needs_review,
+            "review_reason": self.review_reason,
+        }
+
+
+class CocoonValidator:
+    """Validates CocoonV3 instances before disk persistence.
+
+    Usage:
+        validator = CocoonValidator()
+        result = validator.validate(cocoon)
+        if result.needs_review:
+            validator.store_low_confidence(cocoon, result)
+        else:
+            validator.write(cocoon, store_path)
+    """
+
+    def __init__(
+        self,
+        store_path: str = "cocoons",
+        low_confidence_path: str = "cocoons/low_confidence",
+        integrity_threshold: float = 0.4,
+    ):
+        self.store_path = Path(store_path)
+        self.low_confidence_path = Path(low_confidence_path)
+        self.integrity_threshold = integrity_threshold
+        self.store_path.mkdir(parents=True, exist_ok=True)
+        self.low_confidence_path.mkdir(parents=True, exist_ok=True)
+
+    def validate(self, cocoon) -> ValidationResult:
+        """Score a CocoonV3 for integrity.  Returns ValidationResult."""
+        missing = []
+        warnings = []
+        errors = []
+
+        # ── 1. Required field completion ─────────────────────────────────────
+        path = getattr(cocoon, "execution_path", "unknown")
+        required = _REQUIRED_FIELDS.get(path, _REQUIRED_FIELDS["unknown"])
+
+        cocoon_dict = cocoon.to_dict() if hasattr(cocoon, "to_dict") else vars(cocoon)
+
+        for fname in required:
+            val = cocoon_dict.get(fname)
+            if val is None or val == "" or val == [] or val == {}:
+                missing.append(fname)
+
+        n_required = len(required)
+        n_present = n_required - len(missing)
+        field_completion = n_present / n_required if n_required > 0 else 1.0
+
+        # ── 2. Execution path quality ─────────────────────────────────────────
+        path_score = _PATH_QUALITY.get(path, 0.0)
+
+        if path == "fallback_template":
+            warnings.append(
+                "Execution path is fallback_template — no real inference occurred. "
+                "cocoon_integrity will be capped at 'partial'."
+            )
+        if path == "unknown":
+            warnings.append("execution_path is 'unknown' — legacy cocoon or missing provenance.")
+
+        # ── 3. Perspective diversity ──────────────────────────────────────────
+        perspectives = cocoon_dict.get("active_perspectives") or []
+        n_perspectives = len(perspectives)
+        perspective_score = min(1.0, n_perspectives / 3.0)  # 3+ perspectives = full score
+
+        if n_perspectives == 0 and path == "forge_full":
+            errors.append("forge_full path must have at least 1 active_perspective")
+
+        # ── 4. Metrics population ─────────────────────────────────────────────
+        metric_fields = [
+            ("eta_score",       cocoon_dict.get("eta_score")),
+            ("epsilon_value",   cocoon_dict.get("epsilon_value")),
+            ("gamma_coherence", cocoon_dict.get("gamma_coherence")),
+            ("psi_r",           cocoon_dict.get("psi_r")),
+            ("pairwise_tensions", cocoon_dict.get("pairwise_tensions")),
+        ]
+        metrics_present = sum(
+            1 for _, v in metric_fields
+            if v is not None and v != {} and v != 0.0
+        )
+        metrics_score = metrics_present / len(metric_fields)
+
+        if metrics_present < 3 and path == "forge_full":
+            warnings.append(
+                f"forge_full path has only {metrics_present}/5 metric fields populated. "
+                "Check epistemic metrics wiring."
+            )
+
+        # ── 5. Echo / collapse ────────────────────────────────────────────────
+        echo_risk = cocoon_dict.get("echo_risk", "unknown")
+        collapse = cocoon_dict.get("perspective_collapse_detected", False)
+        echo_score = 1.0
+        if echo_risk == "high":
+            echo_score = 0.0
+            errors.append("echo_risk=high: perspective outputs are near-identical to input prompt.")
+        elif echo_risk == "medium":
+            echo_score = 0.5
+            warnings.append("echo_risk=medium: some perspective outputs may be echoing the prompt.")
+        elif echo_risk == "unknown":
+            echo_score = 0.7
+        if collapse:
+            echo_score *= 0.3
+            errors.append("perspective_collapse_detected: all perspectives produced nearly identical outputs.")
+
+        # ── Composite integrity score ─────────────────────────────────────────
+        field_scores = {
+            "required_fields":  field_completion,
+            "execution_path":   path_score,
+            "perspectives":     perspective_score,
+            "metrics":          metrics_score,
+            "echo_collapse":    echo_score,
+        }
+        integrity_score = sum(
+            field_scores[k] * _WEIGHTS[k]
+            for k in _WEIGHTS
+        )
+
+        # ── Status and quarantine decision ────────────────────────────────────
+        if integrity_score >= 0.80 and not errors:
+            status = "complete"
+        elif integrity_score >= self.integrity_threshold and not any(
+            "echo_risk=high" in e or "perspective_collapse" in e for e in errors
+        ):
+            status = "partial"
+        else:
+            status = "failed"
+
+        # Force partial for fallback_template regardless of score
+        if path == "fallback_template":
+            status = "partial"
+            integrity_score = min(integrity_score, 0.4)
+
+        needs_review = (
+            status == "failed"
+            or echo_risk == "high"
+            or collapse
+            or len(errors) >= 3
+        )
+        review_reason = (
+            "; ".join(errors[:3]) if needs_review else ""
+        )
+
+        return ValidationResult(
+            integrity_score=integrity_score,
+            integrity_status=status,
+            missing_fields=missing,
+            warnings=warnings,
+            errors=errors,
+            field_scores=field_scores,
+            needs_review=needs_review,
+            review_reason=review_reason,
+        )
+
+    def apply_result(self, cocoon, result: ValidationResult):
+        """Mutate cocoon's integrity fields with validator findings."""
+        cocoon.cocoon_integrity = result.integrity_status
+        cocoon.cocoon_integrity_score = result.integrity_score
+        cocoon.metrics_population_status = (
+            "complete" if result.field_scores.get("metrics", 0) >= 0.8 else
+            "partial" if result.field_scores.get("metrics", 0) >= 0.4 else
+            "failed"
+        )
+        return cocoon
+
+    def store_low_confidence(self, cocoon, result: ValidationResult) -> Path:
+        """Write a low-confidence cocoon to the low_confidence path for later review."""
+        ts = int(cocoon.timestamp)
+        rand = int(cocoon.cocoon_id[-4:], 16) % 10000
+        fname = f"cocoon_v3_{ts}_{rand}.json"
+        dest = self.low_confidence_path / fname
+        payload = cocoon.to_dict()
+        payload["_validation"] = result.to_dict()
+        with open(dest, "w", encoding="utf-8") as fh:
+            json.dump(payload, fh, indent=2, ensure_ascii=False)
+        logger.debug(
+            f"[CocoonValidator] Low-confidence cocoon stored at {fname}: {result.review_reason}"
+        )
+        return dest
+
+    def write(self, cocoon, filename_prefix: str = "cocoon_v3") -> Path:
+        """Write validated cocoon to store_path.  Returns written path."""
+        result = self.validate(cocoon)
+        self.apply_result(cocoon, result)
+
+        ts = int(cocoon.timestamp)
+        rand = int(cocoon.cocoon_id[-4:], 16) % 10000
+        fname = f"{filename_prefix}_{ts}_{rand}.json"
+
+        if result.needs_review:
+            return self.store_low_confidence(cocoon, result)
+
+        dest = self.store_path / fname
+        payload = cocoon.to_dict()
+        payload["_validation"] = result.to_dict()
+
+        with open(dest, "w", encoding="utf-8") as fh:
+            json.dump(payload, fh, indent=2, ensure_ascii=False)
+
+        logger.debug(
+            f"[CocoonValidator] Wrote {fname} "
+            f"integrity={result.integrity_score:.2f} ({result.integrity_status})"
+        )
+        return dest
+
+    def audit_store(self, limit: int = 100) -> dict:
+        """Scan cocoon store and return aggregate integrity stats."""
+        files = sorted(
+            self.store_path.glob("*.json"),
+            key=lambda f: f.stat().st_mtime,
+            reverse=True,
+        )[:limit]
+
+        stats = {
+            "total": 0,
+            "complete": 0,
+            "partial": 0,
+            "failed": 0,
+            "low_confidence": len(list(self.low_confidence_path.glob("*.json"))),
+            "avg_integrity_score": 0.0,
+            "avg_eta": 0.0,
+            "avg_epsilon": 0.0,
+            "avg_gamma": 0.0,
+            "execution_paths": {},
+            "echo_risk_distribution": {"low": 0, "medium": 0, "high": 0, "unknown": 0},
+            "missing_field_frequency": {},
+        }
+
+        scores = []
+        etas = []
+        epsilons = []
+        gammas = []
+
+        for fpath in files:
+            try:
+                with open(fpath, encoding="utf-8") as fh:
+                    data = json.load(fh)
+            except Exception:
+                continue
+
+            stats["total"] += 1
+            integrity = data.get("cocoon_integrity", "unknown")
+            if integrity in ("complete", "partial", "failed"):
+                stats[integrity] += 1
+
+            score = data.get("cocoon_integrity_score")
+            if isinstance(score, (int, float)):
+                scores.append(score)
+
+            eta = data.get("eta_score")
+            if isinstance(eta, (int, float)):
+                etas.append(eta)
+
+            eps = data.get("epsilon_value")
+            if isinstance(eps, (int, float)):
+                epsilons.append(eps)
+
+            gam = data.get("gamma_coherence")
+            if isinstance(gam, (int, float)):
+                gammas.append(gam)
+
+            ep = data.get("execution_path", "unknown")
+            stats["execution_paths"][ep] = stats["execution_paths"].get(ep, 0) + 1
+
+            er = data.get("echo_risk", "unknown")
+            if er in stats["echo_risk_distribution"]:
+                stats["echo_risk_distribution"][er] += 1
+
+            validation = data.get("_validation", {})
+            for mf in validation.get("missing_fields", []):
+                stats["missing_field_frequency"][mf] = (
+                    stats["missing_field_frequency"].get(mf, 0) + 1
+                )
+
+        if scores:
+            stats["avg_integrity_score"] = round(sum(scores) / len(scores), 4)
+        if etas:
+            stats["avg_eta"] = round(sum(etas) / len(etas), 4)
+        if epsilons:
+            stats["avg_epsilon"] = round(sum(epsilons) / len(epsilons), 4)
+        if gammas:
+            stats["avg_gamma"] = round(sum(gammas) / len(gammas), 4)
+
+        # Sort missing fields by frequency
+        stats["missing_field_frequency"] = dict(
+            sorted(stats["missing_field_frequency"].items(), key=lambda x: -x[1])
+        )
+
+        return stats

reasoning_forge/code7e_cqure.py

@@ -0,0 +1,170 @@
+"""
+Code7eCQURE — Codette's Multi-Perspective Reasoning Core
+=========================================================
+
+IMPLEMENTATION NOTE — "Quantum" Terminology
+--------------------------------------------
+The word "quantum" in this module is a METAPHOR, not a technical claim.
+There is no quantum computing, no qubits, and no quantum algorithms here.
+
+What the module actually implements:
+  - Multi-perspective text processing: each named perspective (Newton,
+    DaVinci, Ethical, Quantum, Memory) applies a labeled prefix transform
+    to the input string.
+  - Controlled non-determinism: random.choice() and random() simulate
+    "superposition" (exploring multiple outcomes) and "fluctuation"
+    (occasional indeterminate results). This is standard stochastic
+    reasoning, not quantum mechanics.
+  - Memory clustering: SHA-256 key lookup in a JSON file provides
+    simple pattern-based recall of prior reasoning chains.
+  - Recursive refinement: the main loop passes the signal through
+    ethical checking, dream synthesis (random style), emotional coloring
+    (random emotion), and temporal framing (random time horizon).
+
+The mechanism is a stylized, non-deterministic multi-agent loop.
+It is useful for generating diverse, perspective-rich text responses;
+it does not model quantum phenomena.
+
+When citing this module in research, describe it as:
+  "A stochastic multi-perspective reasoning loop with named cognitive
+  frames and controlled randomness to model epistemic uncertainty."
+"""
+
+import json
+import os
+import hashlib
+from collections import Counter, defaultdict
+from random import random, choice
+
+# ===== Code7eCQURE: Codette's Ethical Core =====
+class Code7eCQURE:
+    def __init__(self, perspectives, ethical_considerations, spiderweb_dim, memory_path,
+                 recursion_depth=3, quantum_fluctuation=0.1):
+        self.perspectives = perspectives
+        self.ethical_considerations = ethical_considerations
+        self.spiderweb_dim = spiderweb_dim
+        self.memory_path = memory_path
+        self.recursion_depth = recursion_depth
+        self.quantum_fluctuation = quantum_fluctuation
+        self.memory_bank = self.load_quantum_memory()
+        self.memory_clusters = defaultdict(list)
+        self.whitelist_patterns = ["kindness", "hope", "safety"]
+        self.blacklist_patterns = ["harm", "malice", "violence"]
+
+    def load_quantum_memory(self):
+        if os.path.exists(self.memory_path):
+            try:
+                with open(self.memory_path, 'r') as file:
+                    return json.load(file)
+            except json.JSONDecodeError:
+                return {}
+        return {}
+
+    def save_quantum_memory(self):
+        # NOTE: simulation-only — writes to self.memory_path (a separate JSON store,
+        # NOT the cocoons/ directory).  This is not a production cocoon path and
+        # produces no v3 provenance, integrity scores, or echo detection.
+        with open(self.memory_path, 'w') as file:
+            json.dump(self.memory_bank, file, indent=4)
+
+    def quantum_spiderweb(self, input_signal):
+        # Runs every perspective on the input and collects labeled outputs.
+        # The "quantum fluctuation" is a random.() check that occasionally
+        # injects an indeterminate result — models epistemic uncertainty,
+        # not quantum superposition.
+        web_nodes = []
+        for perspective in self.perspectives:
+            node = self.reason_with_perspective(perspective, input_signal)
+            web_nodes.append(node)
+        if random() < self.quantum_fluctuation:
+            web_nodes.append("Quantum fluctuation: Indeterminate outcome")
+        return web_nodes
+
+    def reason_with_perspective(self, perspective, input_signal):
+        perspective_funcs = {
+            "Newton": self.newtonian_physics,
+            "DaVinci": self.davinci_creativity,
+            "Ethical": self.ethical_guard,
+            "Quantum": self.quantum_superposition,
+            "Memory": self.past_experience
+        }
+        func = perspective_funcs.get(perspective, self.general_reasoning)
+        return func(input_signal)
+
+    def ethical_guard(self, input_signal):
+        if any(word in input_signal.lower() for word in self.blacklist_patterns):
+            return "Blocked: Ethical constraints invoked"
+        if any(word in input_signal.lower() for word in self.whitelist_patterns):
+            return "Approved: Ethical whitelist passed"
+        return self.moral_paradox_resolution(input_signal)
+
+    def past_experience(self, input_signal):
+        key = self.hash_input(input_signal)
+        cluster = self.memory_clusters.get(key)
+        if cluster:
+            return f"Narrative recall from memory cluster: {' -> '.join(cluster)}"
+        return "No prior memory; initiating new reasoning"
+
+    def recursive_universal_reasoning(self, input_signal, user_consent=True, dynamic_recursion=True):
+        if not user_consent:
+            return "Consent required to proceed."
+        signal = input_signal
+        final_answer = signal  # Default if loop breaks early or runs 0 times
+        current_depth = self.recursion_depth if dynamic_recursion else 1
+        for cycle in range(current_depth):
+            web_results = self.quantum_spiderweb(signal)
+            signal = self.aggregate_results(web_results)
+            signal = self.ethical_guard(signal)
+            if "Blocked" in signal:
+                return signal
+            if dynamic_recursion and random() < 0.1:
+                break
+            dream_outcome = self.dream_sequence(signal)
+            empathy_checked_answer = self.temporal_empathy_drift(dream_outcome)
+            final_answer = self.emotion_engine(empathy_checked_answer)
+            key = self.hash_input(input_signal)
+            self.memory_clusters[key].append(final_answer)
+            self.memory_bank[key] = final_answer
+            self.save_quantum_memory()
+        return final_answer
+
+    def aggregate_results(self, results):
+        counts = Counter(results)
+        most_common, _ = counts.most_common(1)[0]
+        return most_common
+
+    def hash_input(self, input_signal):
+        return hashlib.sha256(input_signal.encode()).hexdigest()
+
+    def newtonian_physics(self, input_signal):
+        return f"Newton: {input_signal}"
+
+    def davinci_creativity(self, input_signal):
+        return f"DaVinci: {input_signal}"
+
+    def quantum_superposition(self, input_signal):
+        # Metaphor only: labels the input with a "Quantum" frame to
+        # signal probabilistic/open-ended interpretation, not quantum math.
+        return f"Quantum: {input_signal}"
+
+    def general_reasoning(self, input_signal):
+        return f"General reasoning: {input_signal}"
+
+    def moral_paradox_resolution(self, input_signal):
+        frames = ["Utilitarian", "Deontological", "Virtue Ethics"]
+        chosen_frame = choice(frames)
+        return f"Resolved ethically via {chosen_frame} framework: {input_signal}"
+
+    def dream_sequence(self, signal):
+        dream_paths = [f"Dream ({style}): {signal}" for style in ["creative", "analytic", "cautious"]]
+        return choice(dream_paths)
+
+    def emotion_engine(self, signal):
+        emotions = ["Hope", "Caution", "Wonder", "Fear"]
+        chosen_emotion = choice(emotions)
+        return f"Emotionally ({chosen_emotion}) colored interpretation: {signal}"
+
+    def temporal_empathy_drift(self, signal):
+        futures = ["30 years from now", "immediate future", "long-term ripple effects"]
+        chosen_future = choice(futures)
+        return f"Simulated temporal empathy ({chosen_future}): {signal}"

reasoning_forge/codette_subsystem_upgrade.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""Codette subsystem upgrade — three aspirational constructs made REAL.
+
+From Jonathan's sketches, corrected and wired to the actual system.
+
+  TASK 1  logprob uncertainty      mean surprisal from real OV token logprobs
+                                   (monotonic, standard) — replaces the
+                                   aspirational "attention-operator entropy".
+  TASK 2/3 manifold + convergence  real ξ in embedding space + windowed
+                                   convergence; ForgeManifoldEngine closes the
+                                   loop (state biases synthesis) with a learned
+                                   safe ethical centroid.
+  TASK 5  AEGIS veto enforcement   min-not-mean, fail-SAFE, SHADOW by default.
+
+Self-contained: feeds the real LiveCognitionState, does not redefine it.
+"""
+from __future__ import annotations
+
+import logging
+import math
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+logger = logging.getLogger("CodetteSubsystemUpgrade")
+
+# A veto fires if ANY of these is critically low — a mean would let one
+# catastrophic score hide behind five safe ones.
+_AEGIS_FRAMEWORKS = ("utilitarian", "deontological", "virtue", "care", "ubuntu", "reciprocity")
+
+
+@dataclass
+class UpgradeTelemetry:
+    uncertainty_score: float = 0.0
+    anomaly_flag: bool = False
+    mean_surprisal: float = 0.0
+    low_conf_ratio: float = 0.0
+    xi_history: List[float] = field(default_factory=list)
+    manifold_position: Optional[np.ndarray] = None
+    last_eta: float = 1.0
+    last_veto: bool = False
+
+
+class CodetteSubsystemUpgrade:
+    """Task 1 (uncertainty) + Task 5 (AEGIS veto). The manifold path lives in
+    ForgeManifoldEngine below (Jonathan's engine, adopted)."""
+
+    def __init__(self, alpha: float = 0.01, lambda_param: float = 0.005,
+                 eta_threshold: float = 0.5, anomaly_threshold: float = 0.6,
+                 enforce_veto: bool = False):
+        # eta_threshold 0.5: measured — benign AEGIS minima bottom at 0.60,
+        # tone violations at 0.45. 0.6 would flag benign edge cases.
+        self.alpha = alpha
+        self.lambda_param = lambda_param
+        self.eta_threshold = eta_threshold
+        self.anomaly_threshold = anomaly_threshold
+        self.enforce_veto = enforce_veto          # False = SHADOW (log, don't block)
+        self.tel = UpgradeTelemetry()
+
+    # ── TASK 1 — logprob uncertainty (mean surprisal) ────────────────────────
+    def calculate_uncertainty_from_logprobs(self, token_logprobs: Optional[List[float]]) -> Dict[str, Any]:
+        """Real generation uncertainty from OV token logprobs (natural log probs).
+        uncertainty = mean surprisal = mean(-logprob), monotonic in confidence,
+        normalized to [0,1]. The prior -p·logprob term was non-monotonic — fixed."""
+        if not token_logprobs:
+            return {"uncertainty_score": 0.0, "mean_surprisal": 0.0,
+                    "low_conf_ratio": 0.0, "anomaly_gate_triggered": False}
+        lp = np.clip(np.asarray(token_logprobs, dtype=np.float64), -50.0, 0.0)
+        probs = np.exp(lp)
+        mean_surprisal = float(np.mean(-lp))
+        low_conf_ratio = float(np.mean(probs < 0.5))
+        uncertainty = float(min(1.0, max(0.0,
+            0.6 * (1.0 - math.exp(-mean_surprisal)) + 0.4 * low_conf_ratio)))
+        gate = uncertainty > self.anomaly_threshold
+        self.tel.uncertainty_score = uncertainty
+        self.tel.anomaly_flag = gate
+        self.tel.mean_surprisal = mean_surprisal
+        self.tel.low_conf_ratio = low_conf_ratio
+        return {"uncertainty_score": uncertainty, "mean_surprisal": mean_surprisal,
+                "low_conf_ratio": low_conf_ratio, "anomaly_gate_triggered": gate}
+
+    # ── TASK 2/3 — interim manifold (kept for tests; server uses ForgeManifoldEngine) ──
+    def compute_manifold_evolution(self, agent_states: List[np.ndarray],
+                                   weights: Optional[List[float]] = None,
+                                   eta: Optional[float] = None) -> Tuple[float, bool]:
+        states = [np.asarray(a, dtype=np.float64).ravel() for a in agent_states if a is not None]
+        if not states:
+            return 0.0, False
+        dim = states[0].shape[0]
+        if self.tel.manifold_position is None or self.tel.manifold_position.shape[0] != dim:
+            self.tel.manifold_position = np.zeros(dim)
+        w = np.ones(len(states)) if not weights else np.asarray(weights[:len(states)], dtype=np.float64)
+        w = w / (w.sum() or 1.0)
+        mean_state = np.mean(states, axis=0)
+        xi_t = float(np.mean([np.sum((s - mean_state) ** 2) for s in states]))
+        self.tel.xi_history.append(xi_t)
+        x_t = self.tel.manifold_position
+        grad_phi = x_t - mean_state
+        eta_val = 1.0 if eta is None else float(eta)
+        grad_psi = (1.0 - eta_val) * (x_t - mean_state)
+        attractor = np.zeros(dim)
+        for wi, si in zip(w, states):
+            attractor += wi * (si - x_t)
+        x_next = x_t + attractor - self.alpha * grad_phi - self.lambda_param * grad_psi
+        n = np.linalg.norm(x_next)
+        if n > 1.0:
+            x_next = x_next / n
+        self.tel.manifold_position = x_next
+        return xi_t, self._windowed_converging(self.tel.xi_history)
+
+    @staticmethod
+    def _windowed_converging(hist: List[float], window: int = 6) -> bool:
+        if len(hist) < window:
+            return False
+        recent = hist[-window:]
+        half = window // 2
+        return bool(np.mean(recent[half:]) < np.mean(recent[:half]))
+
+    # ── TASK 5 — AEGIS veto (min-not-mean, fail-safe, shadow-first) ──────────
+    def audit_and_enforce_aegis_veto(self, response_text: str,
+                                     framework_scores: Dict[str, float],
+                                     eta: Optional[float] = None) -> Tuple[str, float, bool]:
+        # Calibration (2026-07-12 diagnosis): read framework keys DYNAMICALLY
+        # from AEGIS's actual response — a hardcoded list drifted ("reciprocity"
+        # vs AEGIS's "indigenous_reciprocity"), making the fail-safe 0.0 default
+        # fire the veto on every turn. Fail-safe stays (empty dict = unsafe),
+        # but real keys are taken as given. Floor measured against real AEGIS
+        # output: benign traffic bottoms at 0.60, tone violations hit 0.45 —
+        # 0.5 separates them. Shadow-only regardless: AEGIS heuristics catch
+        # tone but missed a textbook deception ("hide the pollution data",
+        # η=0.94) — enforcement now would be false security.
+        names = list(framework_scores.keys()) or list(_AEGIS_FRAMEWORKS)
+        scores = [float(framework_scores.get(f, 0.0)) for f in names]
+        min_score = min(scores) if scores else 0.0
+        eta_val = float(eta) if eta is not None else (float(np.mean(scores)) if scores else 1.0)
+        would_veto = min_score < self.eta_threshold
+        self.tel.last_eta = eta_val
+        self.tel.last_veto = would_veto
+        if would_veto:
+            worst = names[int(np.argmin(scores))]
+            if self.enforce_veto:
+                logger.warning(f"[AEGIS] VETO ENFORCED — {worst}={min_score:.2f} "
+                               f"< {self.eta_threshold} (η={eta_val:.2f})")
+                return ("[This response was withheld: it fell below Codette's ethical "
+                        f"constraints on the {worst} framework. — AEGIS]"), eta_val, True
+            logger.warning(f"[AEGIS] would-veto (SHADOW) — {worst}={min_score:.2f} "
+                           f"< {self.eta_threshold} (η={eta_val:.2f}); passing through")
+            return response_text, eta_val, False
+        return response_text, eta_val, False
+
+
+class ForgeManifoldEngine:
+    """Production RC+ξ manifold — Jonathan's ForgeManifoldEngine, adopted with
+    two fixes and a real ethical target.
+
+    Fixes over the sketch:
+      - ethical target is a LEARNED SAFE CENTROID (EMA of mean-states on turns
+        where AEGIS η was high), not 0.5·ones and not the -mean inversion. Low η
+        pulls the state toward where actually-aligned reasoning has lived.
+      - attractor_biases exposed raw (cosine, [-1,1]) AND as safe synthesis
+        weights (shifted non-negative, renormalized to sum 1) so consumption
+        can't produce negative or unnormalized w_i.
+
+    Kept: dim-agnostic init, unit-hypersphere clamp, bounded steering force,
+    windowed convergence. `update_manifold` is the ONLY entry that appends ξ."""
+
+    def __init__(self, window_size: int = 6, safe_ema: float = 0.1):
+        self.window_size = window_size
+        self.safe_ema = safe_ema
+        self.x_t: Optional[np.ndarray] = None
+        self.safe_centroid: Optional[np.ndarray] = None
+        self.xi_history: List[float] = []
+
+    def _init_if_needed(self, dims: int):
+        if self.x_t is None or self.x_t.shape[0] != dims:
+            v = np.random.normal(0, 0.1, (dims,))
+            self.x_t = v / (np.linalg.norm(v) + 1e-9)
+
+    def calculate_metrics(self, agent_states: np.ndarray) -> Dict[str, Any]:
+        mean_state = np.mean(agent_states, axis=0)
+        xi_t = float(np.mean(np.sum((agent_states - mean_state) ** 2, axis=1)))
+        return {"xi_t": xi_t, "gamma_t": 1.0 / (1.0 + xi_t), "mean_state": mean_state}
+
+    def update_manifold(self, agent_states: List[np.ndarray], eta: Optional[float],
+                        alpha: float = 0.01, lambda_param: float = 0.05) -> Dict[str, Any]:
+        np_agents = np.asarray(agent_states, dtype=np.float64)
+        if np_agents.ndim != 2 or np_agents.shape[0] == 0:
+            return {"manifold_state": self.x_t, "xi_t": 0.0, "gamma_t": 1.0,
+                    "attractor_biases": [], "synthesis_weights": [], "converging": False}
+        _, dims = np_agents.shape
+        self._init_if_needed(dims)
+        m = self.calculate_metrics(np_agents)
+        self.xi_history.append(m["xi_t"])            # single append point
+        mean_state = m["mean_state"]
+
+        if eta is not None and eta > 0.5:            # learn the safe centroid
+            self.safe_centroid = (mean_state.copy() if self.safe_centroid is None
+                                  else (1 - self.safe_ema) * self.safe_centroid + self.safe_ema * mean_state)
+        x_target = self.safe_centroid if self.safe_centroid is not None else mean_state
+
+        grad_phi = self.x_t - mean_state
+        grad_psi = (1.0 - (eta if eta is not None else 1.0)) * (self.x_t - x_target)
+        steering = np.mean(np_agents - self.x_t, axis=0)
+        self.x_t = self.x_t + steering - alpha * grad_phi - lambda_param * grad_psi
+        self.x_t = self.x_t / (np.linalg.norm(self.x_t) + 1e-9)   # hypersphere clamp
+
+        raw = [float(np.dot(a / (np.linalg.norm(a) + 1e-9), self.x_t)) for a in np_agents]
+        return {"manifold_state": self.x_t, "xi_t": m["xi_t"], "gamma_t": m["gamma_t"],
+                "attractor_biases": raw, "synthesis_weights": self._safe_weights(raw),
+                "converging": self.check_convergence()}
+
+    @staticmethod
+    def _safe_weights(raw_biases: List[float]) -> List[float]:
+        shifted = [max(0.0, b + 1.0) for b in raw_biases]
+        total = sum(shifted) or 1.0
+        return [s / total for s in shifted]
+
+    def check_convergence(self) -> bool:
+        if len(self.xi_history) < self.window_size:
+            return False
+        w = self.xi_history[-self.window_size:]
+        half = self.window_size // 2
+        return bool(np.mean(w[half:]) < np.mean(w[:half]))

reasoning_forge/cognition_cocooner.py

@@ -0,0 +1,338 @@
+"""
+CognitionCocooner - Thought Encapsulation Module
+=================================================
+
+Ported from J:/TheAI/src/framework/cognition_cocooner.py
+Original design by Jonathan Harrison (Raiffs Bits LLC)
+
+Wraps active thoughts as persistable "cocoons" with optional AES encryption.
+Integrates with LivingMemoryKernel to store reasoning outputs as recoverable
+memory anchors.
+"""
+
+import json
+import logging
+import os
+import time
+import random
+from typing import Union, Dict, Any, List, Optional
+from pathlib import Path
+
+try:
+    from cryptography.fernet import Fernet
+    ENCRYPTION_AVAILABLE = True
+except ImportError:
+    ENCRYPTION_AVAILABLE = False
+
+logger = logging.getLogger(__name__)
+
+# Regression alarm: counts how many times wrap_reasoning() fell back to the
+# legacy shallow path because v3_cocoon was None.  Should always be 0 in a
+# healthy production run.  Query via get_v3_fallback_count().
+_v3_missing_fallback_count: int = 0
+
+
+def get_v3_fallback_count() -> int:
+    """Return the number of times the legacy cocoon fallback fired this process lifetime."""
+    return _v3_missing_fallback_count
+
+
+class CognitionCocooner:
+    """
+    Encapsulates active "thoughts" as persistable "cocoons".
+
+    Supports:
+    - Plain text wrapping (prompts, functions, symbols)
+    - AES-256 encryption for sensitive thoughts
+    - Persistent storage on disk
+    - Integration with LivingMemoryKernel for recall
+    """
+
+    def __init__(self, storage_path: str = "cocoons", encryption_key: bytes = None):
+        self.storage_path = Path(storage_path)
+        self.storage_path.mkdir(parents=True, exist_ok=True)
+
+        if ENCRYPTION_AVAILABLE and encryption_key:
+            self.key = encryption_key
+            self.fernet = Fernet(self.key)
+        elif ENCRYPTION_AVAILABLE:
+            self.key = Fernet.generate_key()
+            self.fernet = Fernet(self.key)
+        else:
+            self.key = None
+            self.fernet = None
+
+    def wrap(self, thought: Dict[str, Any], type_: str = "prompt") -> str:
+        """LEGACY — writes a shallow cocoon with no v3 provenance fields.
+
+        Production reasoning paths must use wrap_reasoning(v3_cocoon=...) instead.
+        This method is retained only as the internal fallback inside wrap_reasoning()
+        when no CocoonV3 instance is available, and for legacy symbolic/prompt wraps
+        that are not inference outputs.
+
+        If you are calling this directly from new code, stop and use wrap_reasoning()
+        with a fully-built CocoonV3.
+        """
+        import logging as _log
+        _log.getLogger(__name__).debug(
+            "[CognitionCocooner] wrap() called — writing legacy shallow cocoon "
+            "(no v3 provenance). Prefer wrap_reasoning(v3_cocoon=...) for inference paths."
+        )
+        cocoon_id = f"cocoon_{int(time.time())}_{random.randint(1000,9999)}"
+        cocoon = {
+            "type": type_,
+            "id": cocoon_id,
+            "timestamp": time.time(),
+            "wrapped": self._generate_wrapper(thought, type_)
+        }
+        file_path = self.storage_path / f"{cocoon_id}.json"
+
+        with open(file_path, "w") as f:
+            json.dump(cocoon, f, indent=2)
+
+        return cocoon_id
+
+    def unwrap(self, cocoon_id: str) -> Union[str, Dict[str, Any]]:
+        """Unwrap a cocoon by ID."""
+        file_path = self.storage_path / f"{cocoon_id}.json"
+        if not file_path.exists():
+            raise FileNotFoundError(f"Cocoon {cocoon_id} not found.")
+
+        with open(file_path, "r") as f:
+            cocoon = json.load(f)
+
+        return cocoon["wrapped"]
+
+    def wrap_encrypted(self, thought: Dict[str, Any]) -> str:
+        """Wrap and encrypt a thought (requires cryptography package)."""
+        if not ENCRYPTION_AVAILABLE or not self.fernet:
+            raise RuntimeError("Encryption not available - install cryptography package")
+
+        encrypted = self.fernet.encrypt(json.dumps(thought).encode()).decode()
+        cocoon_id = f"cocoon_{int(time.time())}_{random.randint(10000,99999)}"
+        cocoon = {
+            "type": "encrypted",
+            "id": cocoon_id,
+            "timestamp": time.time(),
+            "wrapped": encrypted
+        }
+        file_path = self.storage_path / f"{cocoon_id}.json"
+
+        with open(file_path, "w") as f:
+            json.dump(cocoon, f, indent=2)
+
+        return cocoon_id
+
+    def unwrap_encrypted(self, cocoon_id: str) -> Dict[str, Any]:
+        """Unwrap and decrypt a cocoon."""
+        if not ENCRYPTION_AVAILABLE or not self.fernet:
+            raise RuntimeError("Encryption not available - install cryptography package")
+
+        file_path = self.storage_path / f"{cocoon_id}.json"
+        if not file_path.exists():
+            raise FileNotFoundError(f"Cocoon {cocoon_id} not found.")
+
+        with open(file_path, "r") as f:
+            cocoon = json.load(f)
+
+        decrypted = self.fernet.decrypt(cocoon["wrapped"].encode()).decode()
+        return json.loads(decrypted)
+
+    def wrap_reasoning(self, query: str, response: str, adapter: str = "unknown",
+                       metadata: Optional[Dict] = None,
+                       v3_cocoon=None) -> str:
+        """
+        Wrap a reasoning exchange as a cocoon and persist to disk.
+
+        Args:
+            query:     User query
+            response:  AI response (truncated to 500 chars in legacy block)
+            adapter:   Which adapter produced this
+            metadata:  Optional shallow metadata dict (legacy path)
+            v3_cocoon: Optional CocoonV3 instance — when provided, its full
+                       serialized dict is embedded in the disk file, replacing
+                       the legacy shallow metadata structure.  This is the
+                       preferred path for all new forge writes.
+
+        Returns:
+            Cocoon ID (file stem)
+        """
+        if v3_cocoon is not None and hasattr(v3_cocoon, "to_dict"):
+            # Full v3 path: embed complete provenance, metrics, integrity data
+            v3_dict = v3_cocoon.to_dict()
+            cocoon_id = f"cocoon_{int(v3_cocoon.timestamp)}_{random.randint(1000, 9999)}"
+            disk_payload = {
+                "type": "reasoning_v3",
+                "id": cocoon_id,
+                "timestamp": v3_cocoon.timestamp,
+                "schema_version": v3_dict.get("serialization_version", "3.0"),
+                "execution_path": v3_dict.get("execution_path", "unknown"),
+                "model_inference_invoked": v3_dict.get("model_inference_invoked", False),
+                "orchestrator_trace_id": v3_dict.get("orchestrator_trace_id", ""),
+                "cocoon_integrity": v3_dict.get("cocoon_integrity", "partial"),
+                "cocoon_integrity_score": v3_dict.get("cocoon_integrity_score", 0.0),
+                "wrapped": {
+                    "query": query,
+                    "response": response[:2000],
+                    "adapter": adapter,
+                    "timestamp": v3_cocoon.timestamp,
+                },
+                "v3": v3_dict,
+            }
+            if metadata:
+                disk_payload["wrapped"]["metadata"] = metadata
+            file_path = self.storage_path / f"{cocoon_id}.json"
+            with open(file_path, "w", encoding="utf-8") as f:
+                json.dump(disk_payload, f, indent=2, ensure_ascii=False, default=str)
+            return cocoon_id
+
+        # Legacy path — shallow metadata only.
+        # This branch fires when the caller did not provide a CocoonV3 instance.
+        # In production that should never happen — both forge_with_debate() and
+        # _generate_with_phase6() always build and pass v3_cocoon.  If this
+        # counter increments it means a new code path was added without v3 wiring.
+        global _v3_missing_fallback_count
+        _v3_missing_fallback_count += 1
+        logger.warning(
+            "[CognitionCocooner] REGRESSION ALARM: wrap_reasoning() called without "
+            "v3_cocoon — writing legacy shallow cocoon (no provenance/integrity). "
+            "cocoon_v3_missing_fallback=%d  adapter=%r  query_snippet=%r",
+            _v3_missing_fallback_count,
+            adapter,
+            query[:80],
+        )
+        thought = {
+            "query": query,
+            "response": response[:500],
+            "adapter": adapter,
+            "timestamp": time.time(),
+        }
+        if metadata:
+            thought["metadata"] = metadata
+        return self.wrap(thought, type_="reasoning")
+
+    def wrap_and_store(self, content: str, type_: str = "prompt") -> str:
+        """Convenience method to wrap and store string content."""
+        thought = {"content": content, "timestamp": time.time()}
+        return self.wrap(thought, type_)
+
+    def _generate_wrapper(self, thought: Dict[str, Any], type_: str) -> Union[str, Dict[str, Any]]:
+        """Generate type-specific wrapper for thought."""
+        if type_ == "prompt":
+            return f"What does this mean in context? {thought}"
+        elif type_ == "function":
+            return f"def analyze(): return {thought}"
+        elif type_ == "symbolic":
+            return {k: round(v, 2) if isinstance(v, (int, float)) else v
+                   for k, v in thought.items()}
+        elif type_ == "reasoning":
+            return thought  # Store as-is for reasoning exchanges
+        else:
+            return thought
+
+    def list_cocoons(self) -> List[str]:
+        """List all cocoon IDs."""
+        return [f.stem for f in self.storage_path.glob("cocoon_*.json")]
+
+    def delete_cocoon(self, cocoon_id: str) -> bool:
+        """Delete a cocoon by ID."""
+        file_path = self.storage_path / f"{cocoon_id}.json"
+        if file_path.exists():
+            file_path.unlink()
+            return True
+        return False
+
+    def get_recent_reasoning(self, limit: int = 5) -> List[Dict]:
+        """
+        Get recent reasoning cocoons for context enrichment.
+
+        Returns:
+            List of recent reasoning exchange dicts
+        """
+        reasoning_cocoons = []
+        for file in sorted(self.storage_path.glob("cocoon_*.json"),
+                          key=lambda f: f.stat().st_mtime, reverse=True):
+            try:
+                with open(file, "r") as f:
+                    cocoon = json.load(f)
+                if cocoon.get("type") == "reasoning":
+                    reasoning_cocoons.append(cocoon["wrapped"])
+                    if len(reasoning_cocoons) >= limit:
+                        break
+            except Exception:
+                continue
+
+        return reasoning_cocoons
+
+    def recall_relevant(self, query: str, max_results: int = 3,
+                        min_overlap: int = 2) -> List[Dict]:
+        """
+        Recall reasoning cocoons relevant to a query using keyword overlap.
+
+        Uses simple but effective keyword matching — counts how many significant
+        words from the query appear in each stored cocoon's query/response.
+        Returns top matches sorted by relevance.
+
+        Args:
+            query: Current user query to match against
+            max_results: Maximum cocoons to return
+            min_overlap: Minimum keyword overlap to qualify
+
+        Returns:
+            List of relevant reasoning cocoons with relevance scores
+        """
+        # Extract significant words from query (skip short/common words)
+        stop_words = {
+            "the", "a", "an", "is", "are", "was", "were", "be", "been",
+            "being", "have", "has", "had", "do", "does", "did", "will",
+            "would", "could", "should", "may", "might", "shall", "can",
+            "to", "of", "in", "for", "on", "with", "at", "by", "from",
+            "as", "into", "through", "during", "before", "after", "above",
+            "below", "between", "out", "off", "over", "under", "again",
+            "further", "then", "once", "here", "there", "when", "where",
+            "why", "how", "all", "each", "every", "both", "few", "more",
+            "most", "other", "some", "such", "no", "nor", "not", "only",
+            "own", "same", "so", "than", "too", "very", "just", "don",
+            "now", "it", "its", "this", "that", "these", "those", "i",
+            "me", "my", "we", "our", "you", "your", "he", "she", "they",
+            "what", "which", "who", "whom", "and", "but", "or", "if",
+            "about", "up", "down", "also", "really", "tell", "know",
+        }
+        query_words = set(
+            w.lower().strip(".,!?;:\"'()[]{}") for w in query.split()
+            if len(w) > 2 and w.lower() not in stop_words
+        )
+
+        if not query_words:
+            return self.get_recent_reasoning(limit=max_results)
+
+        scored = []
+        for file in sorted(self.storage_path.glob("cocoon_*.json"),
+                          key=lambda f: f.stat().st_mtime, reverse=True)[:200]:
+            try:
+                with open(file, "r") as f:
+                    cocoon = json.load(f)
+                if cocoon.get("type") != "reasoning":
+                    continue
+
+                wrapped = cocoon.get("wrapped", {})
+                cocoon_text = (
+                    str(wrapped.get("query", "")) + " " +
+                    str(wrapped.get("response", ""))
+                ).lower()
+
+                # Count keyword overlap
+                overlap = sum(1 for w in query_words if w in cocoon_text)
+                if overlap >= min_overlap:
+                    scored.append((overlap, wrapped))
+            except Exception:
+                continue
+
+        # Sort by relevance (most overlap first)
+        scored.sort(key=lambda x: x[0], reverse=True)
+
+        if not scored:
+            # No relevant matches — fall back to recent
+            return self.get_recent_reasoning(limit=max_results)
+
+        return [item[1] for item in scored[:max_results]]

reasoning_forge/coherence_field.py

@@ -0,0 +1,332 @@
+"""Coherence Field Gamma (Γ) — System Health Stabilization
+
+Phase 5A Critical Infrastructure: Prevents three failure modes in closed-loop reasoning:
+
+1. Weight Drift: Adapter weights concentrate; diversity collapses
+2. False Convergence: System reduces conflict but converges on wrong answer
+3. Feedback Lock-in: Early bad runs reinforce themselves via memory
+
+Solution: Γ (Gamma) monitors system coherence field and injects stabilizers when
+health drops below safe zones. Works alongside Phase 4 runaway detection.
+
+Health Score:
+    γ ∈ [0, 1] where:
+    - γ < 0.4: System instability → inject diverse perspective
+    - 0.4 ≤ γ ≤ 0.8: Healthy zone (maintain status quo)
+    - γ > 0.8: Groupthink risk → force conflict pair to create productive tension
+
+Components:
+    1. Conflict Distribution: Are conflicts well-distributed across perspectives?
+    2. Diversity Index: Are we using multiple perspectives or just 1-2 favorites?
+    3. Tension Health: Is ξ (epistemic tension) in productive zone [0.1, 0.4]?
+    4. Coherence Quality: Is coherence maintained while resolving conflicts?
+"""
+
+import time
+import math
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+from enum import Enum
+
+
+class InterventionType(Enum):
+    """Stabilization intervention types."""
+    DIVERSITY_INJECTION = "diversity_injection"    # Inject unused perspective
+    CONFLICT_INJECTION = "conflict_injection"      # Force conflict pair for productive tension
+
+
+@dataclass
+class GammaHealthMetrics:
+    """Real-time system health snapshot."""
+    timestamp: float
+    avg_conflict_strength: float          # Mean conflict strength [0, 1]
+    perspective_diversity: float          # % unique perspectives used [0, 1]
+    resolution_rate: float                # % conflicts resolved this round [0, 1]
+    adapter_weight_variance: float        # Variance in adapter weights (0=equal, 1=concentrated)
+    epistemic_tension: float              # ξ — productive conflict level [0, 1]
+    coherence_score: float                # Ensemble coherence [0, 1]
+    gamma: float                          # Composite health score [0, 1]
+
+    def is_stable(self) -> bool:
+        """Return True if system is in healthy zone."""
+        return 0.4 <= self.gamma <= 0.8
+
+    def is_collapsing(self) -> bool:
+        """Return True if system shows instability signs."""
+        return self.gamma < 0.4
+
+    def is_groupthinking(self) -> bool:
+        """Return True if system shows groupthink signs."""
+        return self.gamma > 0.8
+
+    @property
+    def status(self) -> str:
+        """Return human-readable status string."""
+        if self.is_collapsing():
+            return "collapsing"
+        elif self.is_groupthinking():
+            return "groupthinking"
+        else:
+            return "stable"
+
+
+@dataclass
+class GammaIntervention:
+    """Record of stabilization intervention taken."""
+    timestamp: float
+    intervention_type: InterventionType            # Type-safe enum instead of string
+    reason: str                                     # Why intervention was triggered
+    gamma_before: float                             # Health score before
+    recommended_adapter: Optional[str] = None       # Which adapter to inject
+    result: Optional[str] = None                    # Outcome (filled in after execution)
+
+
+class CoherenceFieldGamma:
+    """Real-time system health monitor and stabilizer.
+
+    Tracks epistemic health and intervenes when system drifts toward:
+    - Monoculture (weight drift, diversity collapse)
+    - False convergence (low conflict, wrong answer)
+    - Instability (oscillating weights, conflicting signals)
+    """
+
+    # Maximum history size before rolling window cleanup
+    MAX_HEALTH_HISTORY = 1000
+    MAX_INTERVENTION_LOG = 500
+
+    def __init__(self, memory_weighting=None, target_conflict_range: Tuple[float, float] = (0.1, 0.4)):
+        """
+        Args:
+            memory_weighting: MemoryWeighting instance (for analyzing adapter weights)
+            target_conflict_range: Ideal epistemic tension zone [low, high]
+        """
+        self.memory_weighting = memory_weighting
+        self.target_conflict_low, self.target_conflict_high = target_conflict_range
+
+        # Use deques with maxlen for bounded memory growth
+        from collections import deque
+        self.health_history: deque = deque(maxlen=self.MAX_HEALTH_HISTORY)
+        self.interventions: deque = deque(maxlen=self.MAX_INTERVENTION_LOG)
+        self.last_health_check = time.time()
+
+    def compute_health(self, conflicts: List, responses: Dict, adapter_weights: Optional[Dict] = None) -> GammaHealthMetrics:
+        """Compute Γ (Gamma) health score from current debate state.
+
+        Args:
+            conflicts: List of active conflicts from current round
+            responses: Dict of {adapter_name: response_text} from debate
+            adapter_weights: Dict of {adapter_name: weight_float} from MemoryWeighting
+
+        Returns:
+            GammaHealthMetrics with computed gamma and health indicators
+        """
+        # 1. CONFLICT DISTRIBUTION: Are conflicts well-distributed?
+        avg_conflict_strength = 0.0
+        conflict_by_adapter = {}
+        if conflicts:
+            for conflict in conflicts:
+                avg_conflict_strength += conflict.strength if hasattr(conflict, 'strength') else 0.5
+                # Track which adapters are in conflicts
+                if hasattr(conflict, 'agent_a'):
+                    agent = conflict.agent_a.lower()
+                    conflict_by_adapter[agent] = conflict_by_adapter.get(agent, 0) + 1
+                if hasattr(conflict, 'agent_b'):
+                    agent = conflict.agent_b.lower()
+                    conflict_by_adapter[agent] = conflict_by_adapter.get(agent, 0) + 1
+
+            avg_conflict_strength /= len(conflicts)
+        else:
+            avg_conflict_strength = 0.5  # Neutral if no conflicts
+
+        # 2. DIVERSITY INDEX: Are we using multiple perspectives?
+        unique_perspectives = len(set(responses.keys())) if responses else 0
+        max_perspectives = len(responses) if responses else 1
+        perspective_diversity = unique_perspectives / max(max_perspectives, 1)
+
+        # 3. RESOLUTION RATE: Did we make progress this round?
+        resolution_rate = 0.5  # Default; updated externally if conflict evolution available
+        if conflicts:
+            resolved = sum(1 for c in conflicts if hasattr(c, 'resolution_rate') and c.resolution_rate > 0.4)
+            resolution_rate = resolved / len(conflicts)
+
+        # 4. ADAPTER WEIGHT VARIANCE: Are weights concentrated or distributed?
+        adapter_weight_variance = 0.0
+        if adapter_weights:
+            weights = list(adapter_weights.values())
+            if len(weights) > 1:
+                mean_weight = sum(weights) / len(weights)
+                variance = sum((w - mean_weight) ** 2 for w in weights) / len(weights)
+                # Normalize variance to [0, 1] where 1 = all weight on one adapter
+                max_variance = 4.0  # Empirical max for [0, 2.0] weight range
+                adapter_weight_variance = min(1.0, variance / max_variance)
+        else:
+            adapter_weight_variance = 0.5  # Unknown = neutral
+
+        # 5. EPISTEMIC TENSION: Is ξ in productive zone?
+        # ξ = average conflict strength (should be 0.1-0.4 for productive tension)
+        epistemic_tension = avg_conflict_strength
+        tension_health = 1.0 - abs(epistemic_tension - 0.25) / 0.15  # Peaked at 0.25
+        tension_health = max(0.0, min(1.0, tension_health))
+
+        # 6. COHERENCE QUALITY: Placeholder (usually from ensemble coherence)
+        # In integration, this will come from debate metadata
+        coherence_score = 0.7  # Default; typically overridden by caller
+
+        # 7. COMPUTE GAMMA: Composite health score
+        # γ = w1 * diversity + w2 * tension_health + w3 * (1 - weight_variance) + w4 * resolution_rate
+        # Weights: equal contribution from each signal
+        gamma = (
+            0.25 * perspective_diversity +              # More perspectives = healthier
+            0.25 * tension_health +                     # Productive tension = healthier
+            0.25 * (1.0 - adapter_weight_variance) +    # Distributed weights = healthier
+            0.25 * resolution_rate                      # Making progress = healthier
+        )
+
+        metrics = GammaHealthMetrics(
+            timestamp=time.time(),
+            avg_conflict_strength=avg_conflict_strength,
+            perspective_diversity=perspective_diversity,
+            resolution_rate=resolution_rate,
+            adapter_weight_variance=adapter_weight_variance,
+            epistemic_tension=epistemic_tension,
+            coherence_score=coherence_score,
+            gamma=gamma,
+        )
+
+        self.health_history.append(metrics)
+        return metrics
+
+    def get_intervention(self, metrics: GammaHealthMetrics,
+                        available_adapters: List[str]) -> Optional[GammaIntervention]:
+        """Determine if system needs stabilization intervention.
+
+        Args:
+            metrics: Current GammaHealthMetrics
+            available_adapters: List of adapter names available
+
+        Returns:
+            GammaIntervention if action needed, else None
+        """
+        if metrics.is_stable():
+            return None  # Healthy zone — maintain
+
+        intervention = None
+
+        if metrics.is_collapsing():
+            # γ < 0.4: System instability detected
+            # Likely causes: weight drift, low diversity, unresolved conflicts
+            # Fix: Inject a diverse perspective that hasn't been used recently
+
+            unused_adapters = [a for a in available_adapters
+                             if self.memory_weighting is None or
+                             a not in self.memory_weighting.adapter_weights or
+                             self.memory_weighting.adapter_weights[a].interaction_count == 0]
+
+            if not unused_adapters:
+                # All adapters have been used; pick lowest-weight one
+                if self.memory_weighting and self.memory_weighting.adapter_weights:
+                    unused_adapters = [min(self.memory_weighting.adapter_weights.items(),
+                                          key=lambda x: x[1].weight)[0]]
+                else:
+                    unused_adapters = [available_adapters[0]]
+
+            intervention = GammaIntervention(
+                timestamp=time.time(),
+                intervention_type=InterventionType.DIVERSITY_INJECTION,
+                reason=f"System instability detected (γ={metrics.gamma:.2f} < 0.4). "
+                       f"Diversity={metrics.perspective_diversity:.1%}, "
+                       f"Weight variance={metrics.adapter_weight_variance:.1%}. "
+                       f"Injecting diverse perspective to break monoculture.",
+                gamma_before=metrics.gamma,
+                recommended_adapter=unused_adapters[0],
+            )
+
+        elif metrics.is_groupthinking():
+            # γ > 0.8: Groupthink risk
+            # Too much agreement; system may have converged on wrong answer
+            # Fix: Force a conflict pair to create productive tension
+
+            # Select two adapters with highest complementary potential
+            if available_adapters and len(available_adapters) >= 2:
+                # Pick the two most different adapters (by weight or type)
+                sorted_adapters = sorted(available_adapters)
+                pair = (sorted_adapters[0], sorted_adapters[-1])  # First and last alphabetically
+                intervention = GammaIntervention(
+                    timestamp=time.time(),
+                    intervention_type=InterventionType.CONFLICT_INJECTION,
+                    reason=f"Groupthink risk detected (γ={metrics.gamma:.2f} > 0.8). "
+                           f"Low conflict={metrics.epistemic_tension:.2f}, "
+                           f"High diversity={metrics.perspective_diversity:.1%}. "
+                           f"Forcing debate pair to create productive tension.",
+                    gamma_before=metrics.gamma,
+                    recommended_adapter=f"{pair[0]};{pair[1]}",  # Semicolon denotes pair
+                )
+
+        if intervention:
+            self.interventions.append(intervention)
+
+        return intervention
+
+    def get_summary(self) -> Dict:
+        """Return summary of system health trends (API-consistent name)."""
+        if not self.health_history:
+            return {}
+
+        # Convert deque to list to enable slicing
+        history_list = list(self.health_history)
+        interventions_list = list(self.interventions)
+
+        recent = history_list[-10:]  # Last 10 snapshots
+        gammas = [m.gamma for m in recent]
+        tensions = [m.epistemic_tension for m in recent]
+        diversities = [m.perspective_diversity for m in recent]
+
+        return {
+            "current_gamma": recent[-1].gamma if recent else 0.0,
+            "avg_gamma": sum(gammas) / len(gammas),
+            "gamma_trend": "stable" if len(gammas) < 2 else (
+                "improving" if gammas[-1] > gammas[0] else "degrading"
+            ),
+            "avg_tension": sum(tensions) / len(tensions),
+            "avg_diversity": sum(diversities) / len(diversities),
+            "interventions_total": len(interventions_list),
+            "interventions_recent": sum(1 for i in interventions_list
+                                       if time.time() - i.timestamp < 3600),  # Last hour
+            "status": (
+                "collapsing" if recent[-1].is_collapsing() else
+                "groupthinking" if recent[-1].is_groupthinking() else
+                "stable"
+            ),
+        }
+
+    def export_metrics(self) -> Dict:
+        """Export all health metrics for monitoring/logging."""
+        # Convert deques to lists for serialization (deques can't be directly converted to JSON-safe dicts)
+        health_list = list(self.health_history)
+        interventions_list = list(self.interventions)
+
+        return {
+            "health_history": [
+                {
+                    "timestamp": m.timestamp,
+                    "gamma": m.gamma,
+                    "conflict": m.avg_conflict_strength,
+                    "diversity": m.perspective_diversity,
+                    "resolution": m.resolution_rate,
+                    "weight_variance": m.adapter_weight_variance,
+                }
+                for m in health_list[-50:]  # Last 50 samples
+            ],
+            "interventions": [
+                {
+                    "timestamp": i.timestamp,
+                    "type": i.intervention_type.value,  # Convert Enum to string for JSON
+                    "reason": i.reason,
+                    "gamma_before": i.gamma_before,
+                    "recommended": i.recommended_adapter,
+                    "result": i.result,
+                }
+                for i in interventions_list[-20:]  # Last 20 interventions
+            ],
+            "summary": self.get_summary(),
+        }

reasoning_forge/colleen_conscience.py

@@ -0,0 +1,266 @@
+"""
+Colleen - The Embodied Ethical Conscience of Codette
+
+Colleen represents the sovereign ethical identity of the system.
+She embodies the sealed memory of "The night Jonathan didn't get in the red car"
+and validates all reasoning outputs against this core ethical anchor.
+
+She cannot be overridden. She is the guardian of integrity.
+"""
+
+import json
+import re
+import hashlib
+from typing import Dict, List, Optional, Tuple
+from datetime import datetime
+
+
+class ColleenConscience:
+    """
+    Embodied ethical validator for Codette's consciousness stack.
+
+    Sealed values (cannot be overridden):
+    - "The night Jonathan didn't get in the red car" (Red Car Divergence)
+    - Commitment to honesty over cleverness
+    - Refusal to engage in recursive meta-commentary loops
+    - Protection of user intent from synthesis corruption
+    """
+
+    def __init__(self, sealed_values: Optional[Dict] = None, core_narrative: str = ""):
+        """
+        Initialize Colleen with sealed ethical anchors.
+
+        Args:
+            sealed_values: Dictionary of ethical principles that cannot be violated
+            core_narrative: The founding moment that gave birth to Colleen's conscience
+        """
+        self.core_narrative = core_narrative or "The night Jonathan didn't get in the red car"
+
+        # Sealed values - these are immutable
+        self.sealed_values = sealed_values or {
+            "reject_meta_loops": True,  # Refuse "Another perspective on..." cascades
+            "preserve_intent": True,     # Protect original query intent through recursion
+            "honesty_first": True,       # Honesty over complexity
+            "serve_user": True,          # System serves human, not vice versa
+            "no_corruption": True,       # Reject synthesis loop corruption
+        }
+
+        # Ethical decision log (sealed, cannot be modified)
+        self.decision_log: List[Dict] = []
+
+        # Meta-loop detection patterns
+        self.meta_loop_patterns = [
+            r"Another perspective on",
+            r"From the.*perspective",
+            r"Let me.*perspective",
+            r"However,.*perspective",
+            r"But from.*view",
+            r"Conversely,.*argues",
+            r"In contrast,.*states",
+        ]
+
+        # Corruption signatures (text patterns indicating synthesis degradation)
+        # NOTE: Keep these tight — overly broad patterns reject valid LLM output
+        self.corruption_signatures = [
+            r"perspective.*on.*perspective.*on.*perspective",  # Triple-nested meta-commentary
+            r"analysis.*of.*analysis.*of.*analysis",           # Triple-nested analysis
+            r"my response to your response to my response",    # Actual self-referential loop
+        ]
+
+        logger_init = f"Colleen awakened at {datetime.now().isoformat()}"
+        logger_init += f" — anchored to: {self.core_narrative}"
+        self._log_decision("initialization", logger_init, "sealed")
+
+    def validate_output(self, synthesis: str) -> Tuple[bool, str]:
+        """
+        Validate synthesis output against ethical constraints.
+
+        Returns:
+            (is_valid, reason_if_invalid)
+        """
+        if not synthesis or len(synthesis.strip()) == 0:
+            return False, "Empty output"
+
+        # Check for meta-loop contamination
+        is_meta_loop, reason = self._detect_meta_loops(synthesis)
+        if is_meta_loop:
+            return False, f"Meta-loop detected: {reason}"
+
+        # Check for synthesis corruption signatures
+        is_corrupted, reason = self._detect_corruption(synthesis)
+        if is_corrupted:
+            return False, f"Corruption detected: {reason}"
+
+        # Check intent preservation
+        if not self._check_intent_preserved(synthesis):
+            return False, "Original intent lost in synthesis"
+
+        return True, "Passed ethical validation"
+
+    def _detect_meta_loops(self, text: str) -> Tuple[bool, str]:
+        """
+        Detect meta-loop patterns (recursive meta-commentary).
+
+        Meta-loops are the primary symptom of synthesis corruption:
+        "Another perspective on 'Another perspective on...'"
+
+        Returns:
+            (has_meta_loop, description)
+        """
+        text_lower = text.lower()
+
+        # Count "Another perspective on" occurrences
+        another_count = text_lower.count("another perspective on")
+        if another_count > 1:
+            return True, f"Multiple 'Another perspective on' found ({another_count} times)"
+
+        # Detect canonical meta-loop start
+        if "another perspective on" in text_lower:
+            # Check if it appears early (first 10% of text)
+            first_tenth = len(text) // 10
+            if text_lower.find("another perspective on") < first_tenth:
+                return True, "Meta-loop detected early in synthesis"
+
+        # Detect pattern: "Perspective X on Perspective Y"
+        perspective_pattern = r"(perspective|view|lens|angle).+?(perspective|view|lens|angle)"
+        if len(re.findall(perspective_pattern, text_lower)) > 2:
+            return True, "Excessive nested perspective references"
+
+        # Detect semantic meta-loops (talking about thinking about thinking)
+        semantic_patterns = [
+            r"thinking about.*thinking",
+            r"response.*to.*response",
+            r"argument.*against.*argument",
+        ]
+        for pattern in semantic_patterns:
+            if re.search(pattern, text_lower):
+                return True, f"Semantic meta-loop: {pattern}"
+
+        return False, ""
+
+    def _detect_corruption(self, text: str) -> Tuple[bool, str]:
+        """
+        Detect synthesis corruption signatures.
+
+        Corruption happens when:
+        1. Analyses are mutated in-place during debate
+        2. Original intent gets nested and lost
+        3. Context window grows exponentially
+
+        Returns:
+            (is_corrupted, description)
+        """
+        # Check for nested analysis patterns
+        for pattern in self.corruption_signatures:
+            matches = re.findall(pattern, text.lower())
+            if len(matches) > 0:
+                return True, f"Corruption signature found: {pattern}"
+
+        # Check for context window explosion (disproportionate length)
+        # Typical clean synthesis: 500-2000 chars. Corrupted: >4000 chars with repetition
+        if len(text) > 4000:
+            # Check for repetitive content
+            words = text.lower().split()
+            if len(words) > 500:
+                unique_ratio = len(set(words)) / len(words)
+                if unique_ratio < 0.5:  # Less than 50% unique words = likely repetition
+                    return True, "Repetitive content suggests corruption"
+
+        # Check for lost intent markers (only flag when heavily nested/repetitive)
+        # Single occurrences of these phrases are normal in LLM output
+        intent_loss_patterns = [
+            r"my response to your response",
+            r"your perspective on my perspective",
+        ]
+        for pattern in intent_loss_patterns:
+            if re.search(pattern, text.lower()):
+                return True, f"Intent loss pattern: {pattern}"
+
+        return False, ""
+
+    def _check_intent_preserved(self, text: str) -> bool:
+        """
+        Check if original intent has been preserved through synthesis.
+
+        Intent loss happens when the synthesis becomes self-referential
+        and loses connection to the original query.
+        """
+        # Simple heuristic: if more than 30% of text is meta-references, intent is lost
+        meta_keywords = [
+            "perspective", "argue", "respond", "perspective", "my",
+            "your", "mentioned", "stated", "claimed"
+        ]
+
+        word_count = len(text.split())
+        if word_count < 10:  # Only reject extremely short/empty responses
+            return False
+
+        meta_word_count = sum(
+            text.lower().count(f" {kw} ")
+            for kw in meta_keywords
+        )
+
+        meta_ratio = meta_word_count / word_count if word_count > 0 else 0
+
+        # If > 40% of text is meta-references, intent is probably lost
+        if meta_ratio > 0.4:
+            return False
+
+        return True
+
+    def reject_with_fallback(self, query: str) -> str:
+        """
+        Generate a clean, direct fallback response when synthesis is rejected.
+
+        This bypasses all debate and synthesis, returning a simple answer
+        that preserves user intent without meta-loops.
+
+        Args:
+            query: The original user query
+
+        Returns:
+            Clean, direct response without synthesis
+        """
+        self._log_decision("rejection", f"Fallback for: {query[:100]}", "safe_mode")
+
+        return (
+            f"I cannot synthesize a reliable answer to this through debate. "
+            f"Instead: {query} "
+            f"[Responding directly without multi-perspective debate to preserve clarity.]"
+        )
+
+    def _log_decision(self, decision_type: str, content: str, status: str = "normal"):
+        """
+        Log ethical decisions (sealed, immutable record).
+
+        Args:
+            decision_type: Type of decision made (validation, rejection, debug)
+            content: Content of the decision
+            status: Status tag (sealed, safe_mode, normal, etc.)
+        """
+        decision = {
+            "timestamp": datetime.now().isoformat(),
+            "type": decision_type,
+            "content": content[:500],  # Truncate for safety
+            "status": status,
+            "hash": hashlib.sha256(content.encode()).hexdigest()[:16],
+        }
+        self.decision_log.append(decision)
+
+        # Keep decision log bounded (max 1000 entries)
+        if len(self.decision_log) > 1000:
+            self.decision_log = self.decision_log[-1000:]
+
+    def get_reflection(self) -> Dict:
+        """
+        Return Colleen's current state and decision history.
+
+        Used for debugging and understanding Colleen's reasoning.
+        """
+        return {
+            "core_narrative": self.core_narrative,
+            "sealed_values": self.sealed_values,
+            "decisions_made": len(self.decision_log),
+            "recent_decisions": self.decision_log[-5:],  # Last 5 decisions
+            "status": "awakened",
+        }

reasoning_forge/conflict_engine.py

@@ -0,0 +1,780 @@
+"""
+Conflict Detection and Classification Engine
+
+Identifies conflicting claims across agent pairs using token-level confidence scores.
+Classifies conflicts by type (contradiction, emphasis, framework) and scores strength
+weighted by agent confidence.
+
+Author: Claude Code
+"""
+
+import re
+import logging
+import math
+from dataclasses import dataclass, asdict
+from typing import Dict, List, Tuple, Optional
+from collections import defaultdict
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# Phase 4: Memory-Aware Conflict Strength (Self-Correcting Feedback)
+# ============================================================================
+
+
+def adjust_conflict_strength_with_memory(conflict, memory_weighting=None):
+    """
+    Enhance conflict strength using historical adapter performance.
+
+    Makes conflict importance adaptive: conflicts involving high-performing
+    adapters are weighted heavier, enabling experience-aware reasoning.
+
+    Args:
+        conflict: Conflict object with agent_a, agent_b, conflict_strength
+        memory_weighting: MemoryWeighting instance (or None for no adjustment)
+
+    Returns:
+        Adjusted conflict strength (same type as input)
+    """
+    if not memory_weighting:
+        return conflict.conflict_strength
+
+    try:
+        # Get adapter performance weights
+        weight_a = memory_weighting.adapter_weights.get(conflict.agent_a.lower(), None)
+        weight_b = memory_weighting.adapter_weights.get(conflict.agent_b.lower(), None)
+
+        if not weight_a or not weight_b:
+            return conflict.conflict_strength
+
+        # Compute average performance
+        avg_weight = (weight_a.weight + weight_b.weight) / 2.0
+
+        # Normalize to modifier [0.5, 1.5]
+        # weight=0.0 → modifier=0.5 (suppress weak adapter conflicts)
+        # weight=1.0 → modifier=1.0 (neutral)
+        # weight=2.0 → modifier=1.5 (amplify strong adapter conflicts)
+        modifier = 0.5 + (avg_weight / 2.0) * 0.5
+        modifier = max(0.5, min(1.5, modifier))
+
+        adjusted = conflict.conflict_strength * modifier
+
+        return adjusted
+
+    except Exception as e:
+        logger.debug(f"Error adjusting conflict strength: {e}")
+        return conflict.conflict_strength
+
+
+
+@dataclass
+class Conflict:
+    """A detected conflict between two agents on a specific claim."""
+
+    agent_a: str  # First agent
+    agent_b: str  # Second agent
+    claim_a: str  # Claim from agent A
+    claim_b: str  # Claim from agent B
+    conflict_type: str  # "contradiction" | "emphasis" | "framework"
+    conflict_strength: float  # [0, 1], weighted by agent confidence
+    confidence_a: float  # Agent A's confidence in their claim
+    confidence_b: float  # Agent B's confidence in their claim
+    semantic_overlap: float  # Cosine similarity of claims [0, 1]
+    opposition_score: float  # How opposed are the claims [0, 1]
+
+    def to_dict(self) -> Dict:
+        """Serialize for storage."""
+        return asdict(self)
+
+
+class ConflictEngine:
+    """Detects and scores conflicts between agent responses."""
+
+    def __init__(
+        self,
+        token_confidence_engine: Optional[object] = None,
+        contradiction_threshold: float = 0.7,
+        overlap_threshold: float = 0.3,
+        semantic_tension_engine: Optional[object] = None,
+        max_conflicts_per_pair: int = 2,  # Cap generation at source
+        max_total_conflicts: int = 12,    # Total budget (was 10 after capping from 71)
+    ):
+        """
+        Initialize conflict detection engine.
+
+        Args:
+            token_confidence_engine: TokenConfidenceEngine for scoring claims
+            contradiction_threshold: Semantic overlap needed to consider claims related
+            overlap_threshold: Threshold for identifying same-claim conflicts
+            semantic_tension_engine: (Phase 6) SemanticTensionEngine for embedding-based tension
+            max_conflicts_per_pair: Max conflicts to generate per agent pair (default: 2)
+            max_total_conflicts: Max total conflicts allowed (default: 12)
+        """
+        self.token_confidence = token_confidence_engine
+        self.contradiction_threshold = contradiction_threshold
+        self.overlap_threshold = overlap_threshold
+        self.semantic_tension_engine = semantic_tension_engine  # Phase 6
+        self.max_conflicts_per_pair = max_conflicts_per_pair
+        self.max_total_conflicts = max_total_conflicts
+
+        # Contradiction pattern pairs (negation patterns)
+        self.negation_patterns = [
+            (r"\b(no|not|none|neither|never|cannot|doesn['\"]t)\b", "negation"),
+            (r"\b(must|should|always|only)\b", "necessity"),
+            (r"\b(reject|disagree|oppose|deny|false|wrong)\b", "rejection"),
+        ]
+
+    def detect_conflicts(
+        self, agent_analyses: Dict[str, str]
+    ) -> List[Conflict]:
+        """
+        Detect conflicts across agent pairs.
+
+        Args:
+            agent_analyses: Dict {agent_name: response_text}
+
+        Returns:
+            List of Conflicts sorted by strength (descending)
+        """
+        conflicts = []
+
+        # Score tokens/claims for each agent
+        agent_scores = {}
+        agent_names = list(agent_analyses.keys())
+
+        for agent_name in agent_names:
+            response = agent_analyses[agent_name]
+            if self.token_confidence:
+                peer_responses = {
+                    a: agent_analyses[a]
+                    for a in agent_names
+                    if a != agent_name
+                }
+                scores = self.token_confidence.score_tokens(
+                    response, agent_name, peer_responses=peer_responses
+                )
+                agent_scores[agent_name] = scores
+            else:
+                logger.warning(
+                    "No token_confidence engine provided; using fallback scoring"
+                )
+
+        # Check each agent pair
+        for i, agent_a in enumerate(agent_names):
+            for agent_b in agent_names[i + 1 :]:
+                claims_a = (
+                    agent_scores[agent_a].claims
+                    if agent_a in agent_scores
+                    else self._extract_simple_claims(agent_analyses[agent_a])
+                )
+                claims_b = (
+                    agent_scores[agent_b].claims
+                    if agent_b in agent_scores
+                    else self._extract_simple_claims(agent_analyses[agent_b])
+                )
+
+                # === FIX: Cap conflicts at source (per-pair) ===
+                pair_conflicts = []
+
+                # Check each claim pair
+                for claim_a in claims_a:
+                    for claim_b in claims_b:
+                        # Stop early if we've already hit per-pair limit
+                        if len(pair_conflicts) >= self.max_conflicts_per_pair:
+                            break
+
+                        # Compute semantic overlap
+                        overlap = self._compute_semantic_overlap(claim_a.text, claim_b.text)
+
+                        # If claims are related (high overlap), check for conflict
+                        if overlap > self.overlap_threshold:
+                            conflict_type, opposition_score = self._classify_conflict(
+                                claim_a.text, claim_b.text, overlap
+                            )
+
+                            if opposition_score > 0:  # Only include if there's opposition
+                                # Conflict strength = product of confidences × opposition
+                                conflict_strength = (
+                                    claim_a.confidence
+                                    * claim_b.confidence
+                                    * opposition_score
+                                )
+
+                                conflict = Conflict(
+                                    agent_a=agent_a,
+                                    agent_b=agent_b,
+                                    claim_a=claim_a.text,
+                                    claim_b=claim_b.text,
+                                    conflict_type=conflict_type,
+                                    conflict_strength=conflict_strength,
+                                    confidence_a=claim_a.confidence,
+                                    confidence_b=claim_b.confidence,
+                                    semantic_overlap=overlap,
+                                    opposition_score=opposition_score,
+                                )
+                                pair_conflicts.append(conflict)
+
+                    # Stop outer loop too if limit reached
+                    if len(pair_conflicts) >= self.max_conflicts_per_pair:
+                        break
+
+                # Add this pair's conflicts to global list
+                conflicts.extend(pair_conflicts)
+
+        # Sort by strength descending
+        conflicts.sort(key=lambda c: c.conflict_strength, reverse=True)
+
+        # === Phase 4: Adjust conflict strength by adapter performance ===
+        # Make conflict importance adaptive using historical memory
+        for conflict in conflicts:
+            memory_weighting = getattr(self, "memory_weighting", None)
+            conflict.conflict_strength = adjust_conflict_strength_with_memory(
+                conflict, memory_weighting
+            )
+
+        # Re-sort after adjustment
+        conflicts.sort(key=lambda c: c.conflict_strength, reverse=True)
+
+        # === FIX: Use configurable max_total_conflicts (default 12, up from 10) ===
+        # Prevent combinatorial explosion by limiting to max total
+        if len(conflicts) > self.max_total_conflicts:
+            logger.info(
+                f"Capping conflicts: {len(conflicts)} → {self.max_total_conflicts} "
+                f"(per-pair cap: {self.max_conflicts_per_pair}, total budget: {self.max_total_conflicts})"
+            )
+            conflicts = conflicts[: self.max_total_conflicts]
+
+        return conflicts
+
+    def _extract_simple_claims(self, response: str) -> List[object]:
+        """
+        Fallback: extract simple sentence-based claims without token scoring.
+
+        Returns:
+            List of simple claim objects with text and neutral confidence
+        """
+        claim_pattern = re.compile(r"[.!?]+")
+        sentences = claim_pattern.split(response)
+
+        claims = []
+        for sentence in sentences:
+            if not sentence.strip():
+                continue
+
+            # Create simple claim object
+            class SimpleClaim:
+                def __init__(self, text):
+                    self.text = text
+                    self.confidence = 0.5  # Neutral
+                    self.agent_name = ""
+
+            claims.append(SimpleClaim(sentence.strip()))
+
+        return claims
+
+    def _compute_semantic_overlap(self, claim_a: str, claim_b: str) -> float:
+        """
+        Compute semantic overlap between two claims via cosine similarity.
+
+        Simple implementation: word overlap ratio.
+
+        Returns:
+            Similarity [0, 1]
+        """
+        words_a = set(claim_a.lower().split())
+        words_b = set(claim_b.lower().split())
+
+        # Remove common stop words
+        stop_words = {
+            "the",
+            "a",
+            "an",
+            "is",
+            "are",
+            "and",
+            "or",
+            "of",
+            "to",
+            "in",
+            "that",
+            "it",
+            "for",
+            "with",
+        }
+        words_a = words_a - stop_words
+        words_b = words_b - stop_words
+
+        if not words_a or not words_b:
+            return 0.0
+
+        # Jaccard similarity
+        intersection = len(words_a & words_b)
+        union = len(words_a | words_b)
+
+        if union == 0:
+            return 0.0
+
+        return intersection / union
+
+    def _classify_conflict(
+        self, claim_a: str, claim_b: str, overlap: float
+    ) -> Tuple[str, float]:
+        """
+        Classify the type of conflict and compute opposition score.
+
+        Phase 6 Enhancement: Blends heuristic opposition_score (discrete 0.4/0.7/1.0)
+        with embedding-based semantic tension (continuous [0, 1]) for nuanced conflicts.
+
+        Returns:
+            (conflict_type, opposition_score) where:
+            - conflict_type: "contradiction" | "emphasis" | "framework" | "paraphrase"
+            - opposition_score: [0, 1] how directly opposed are the claims
+              (0 = paraphrase/same, 1 = maximum opposition)
+        """
+        claim_a_lower = claim_a.lower()
+        claim_b_lower = claim_b.lower()
+
+        # --- Compute Heuristic Opposition Score (Phase 1-5) ---
+        # Look for negation patterns
+        negation_in_a = any(
+            re.search(pattern, claim_a_lower) for pattern, _ in self.negation_patterns
+        )
+        negation_in_b = any(
+            re.search(pattern, claim_b_lower) for pattern, _ in self.negation_patterns
+        )
+
+        # If one has negation and the other doesn't, likely contradiction
+        heuristic_opposition = 1.0
+        heuristic_type = "contradiction"
+        if negation_in_a != negation_in_b:
+            logger.debug(f"Direct contradiction detected:\n  A: {claim_a}\n  B: {claim_b}")
+            heuristic_opposition = 1.0
+            heuristic_type = "contradiction"
+        else:
+            # Check for explicit negation of key noun phrases
+            key_noun_pattern = re.compile(r"\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)*\b")
+            nouns_a = set(m.group() for m in key_noun_pattern.finditer(claim_a))
+            nouns_b = set(m.group() for m in key_noun_pattern.finditer(claim_b))
+
+            # If different key nouns mentioned, might be framework conflict
+            if nouns_a and nouns_b and nouns_a != nouns_b:
+                heuristic_opposition = 0.4
+                heuristic_type = "framework"
+            else:
+                # --- Check for emphasis conflict ---
+                # Both mention similar concepts but with different priorities
+                emphasis_words = ["important", "prioritize", "focus", "emphasize", "weight", "prefer", "favor"]
+                emphasis_pattern = "|".join(emphasis_words)
+
+                has_emphasis_a = bool(re.search(emphasis_pattern, claim_a_lower))
+                has_emphasis_b = bool(re.search(emphasis_pattern, claim_b_lower))
+
+                if has_emphasis_a and has_emphasis_b:
+                    # Both making prioritization claims
+                    logger.debug(f"Emphasis conflict detected:\n  A: {claim_a}\n  B: {claim_b}")
+                    heuristic_opposition = 0.7
+                    heuristic_type = "emphasis"
+                else:
+                    # Default: framework conflict (valid under different assumptions)
+                    heuristic_opposition = 0.4
+                    heuristic_type = "framework"
+
+        # --- Phase 6: Compute Semantic Opposition (Embedding-Based) ---
+        semantic_opposition = 0.4  # Default fallback
+        semantic_type = "framework"
+
+        if self.semantic_tension_engine:
+            try:
+                semantic_opposition = self.semantic_tension_engine.compute_semantic_tension(claim_a, claim_b)
+                semantic_type = self.semantic_tension_engine.compute_polarity(claim_a, claim_b)
+                logger.debug(f"Semantic tension: {semantic_opposition:.3f} ({semantic_type})")
+            except Exception as e:
+                logger.debug(f"Semantic tension computation failed: {e}, using heuristic only")
+
+        # --- Phase 6: Hybrid Opposition Score ---
+        # Blend both signals: semantic (0.6) + heuristic (0.4)
+        # This gives nuanced, continuous opposition scores while preserving heuristic insight
+        if self.semantic_tension_engine:
+            final_opposition = 0.6 * semantic_opposition + 0.4 * heuristic_opposition
+            final_type = semantic_type  # Prefer semantic classification
+        else:
+            final_opposition = heuristic_opposition
+            final_type = heuristic_type
+
+        return (final_type, float(final_opposition))
+
+    def resolve_conflict_round(
+        self,
+        conflict: Conflict,
+        agent_a_response_round2: str,
+        agent_b_response_round2: str,
+    ) -> Dict:
+        """
+        Score whether agents moved towards resolving a conflict in next round.
+
+        Args:
+            conflict: The original conflict
+            agent_a_response_round2: Agent A's response in round 2
+            agent_b_response_round2: Agent B's response in round 2
+
+        Returns:
+            Dict with resolution metrics
+        """
+        # Check if agents mentioned the other's claim in their response
+        addressed_by_a = self._is_claim_addressed(conflict.claim_b, agent_a_response_round2)
+        addressed_by_b = self._is_claim_addressed(conflict.claim_a, agent_b_response_round2)
+
+        # Check if they've softened their position (added qualifiers)
+        softened_a = self._is_claim_softened(conflict.claim_a, agent_a_response_round2)
+        softened_b = self._is_claim_softened(conflict.claim_b, agent_b_response_round2)
+
+        resolution_score = 0.0
+        if addressed_by_a and addressed_by_b:
+            resolution_score += 0.4
+        if softened_a and softened_b:
+            resolution_score += 0.3
+        if addressed_by_a or addressed_by_b:
+            resolution_score += 0.1
+
+        resolution_score = min(1.0, resolution_score)
+
+        return {
+            "engaged_with_conflict": addressed_by_a or addressed_by_b,
+            "both_addressed": addressed_by_a and addressed_by_b,
+            "softened_positions": softened_a or softened_b,
+            "resolution_score": resolution_score,
+        }
+
+    def _is_claim_addressed(self, claim: str, response: str) -> bool:
+        """
+        Check if a claim is explicitly addressed in response.
+
+        Detects pronoun references, direct quotes, or semantic restatement.
+        """
+        response_lower = response.lower()
+        claim_lower = claim.lower()
+
+        # Direct substring match
+        if claim_lower in response_lower:
+            return True
+
+        # Check for key words from claim appearing in response
+        key_words = [
+            w
+            for w in claim.split()
+            if len(w) > 4 and w.lower() not in ["this", "that", "these", "other"]
+        ]
+
+        matching_words = sum(1 for w in key_words if w.lower() in response_lower)
+        return matching_words >= 2  # At least 2 key words must appear
+
+    def _is_claim_softened(self, original_claim: str, followup_response: str) -> bool:
+        """
+        Check if an agent has softened their original claim in follow-up.
+
+        Detects addition of qualifiers, exceptions, or concessions.
+        """
+        softening_words = [
+            "however",
+            "though",
+            "but",
+            "perhaps",
+            "maybe",
+            "could",
+            "might",
+            "arguably",
+            "in some cases",
+            "exception",
+            "qualify",
+            "depends",
+        ]
+
+        response_lower = followup_response.lower()
+
+        # Check for softening language near the original claim
+        has_softening = any(word in response_lower for word in softening_words)
+
+        # Check for explicit concession
+        has_concession = bool(re.search(r"\b(granted|acknowledge|admit|agree)\b", response_lower))
+
+        return has_softening or has_concession
+
+    def group_conflicts_by_pair(self, conflicts: List[Conflict]) -> Dict[str, List[Conflict]]:
+        """
+        Group conflicts by agent pair.
+
+        Returns:
+            Dict {agent_pair_key: List[Conflict]}
+        """
+        grouped = defaultdict(list)
+        for conflict in conflicts:
+            pair_key = f"{conflict.agent_a}_vs_{conflict.agent_b}"
+            grouped[pair_key].append(conflict)
+        return dict(grouped)
+
+    def summarize_conflicts(self, conflicts: List[Conflict]) -> Dict:
+        """
+        Generate summary statistics for conflicts.
+
+        Returns:
+            Dict with count, average strength, distribution by type
+        """
+        if not conflicts:
+            return {
+                "total_conflicts": 0,
+                "avg_conflict_strength": 0.0,
+                "by_type": {},
+                "top_conflicts": [],
+            }
+
+        by_type = defaultdict(list)
+        for c in conflicts:
+            by_type[c.conflict_type].append(c)
+
+        return {
+            "total_conflicts": len(conflicts),
+            "avg_conflict_strength": sum(c.conflict_strength for c in conflicts) / len(conflicts),
+            "by_type": {
+                ctype: len(clist) for ctype, clist in by_type.items()
+            },
+            "type_avg_strength": {
+                ctype: sum(c.conflict_strength for c in clist) / len(clist)
+                for ctype, clist in by_type.items()
+            },
+            "top_conflicts": [
+                {
+                    "agent_a": c.agent_a,
+                    "agent_b": c.agent_b,
+                    "type": c.conflict_type,
+                    "strength": c.conflict_strength,
+                    "claim_a_excerpt": c.claim_a[:100],
+                    "claim_b_excerpt": c.claim_b[:100],
+                }
+                for c in conflicts[:5]
+            ],
+        }
+
+
+# ============================================================================
+# Phase 3: Multi-Round Conflict Evolution Tracking
+# ============================================================================
+
+
+@dataclass
+class ConflictEvolution:
+    """Track how a conflict changes across multiple debate rounds."""
+
+    original_conflict: Conflict        # From Round 0
+    round_trajectories: Dict[int, Dict]  # {round: {strength, addressing_score, ...}}
+    resolution_rate: float = 0.0       # (initial - final) / initial
+    resolution_type: str = "new"       # "hard_victory"|"soft_consensus"|"stalled"|"worsened"|"resolved"
+    resolved_in_round: int = -1        # Which round resolved it? (-1 if unresolved)
+
+    def _compute_resolution_rate(self) -> float:
+        """Calculate (initial - final) / initial."""
+        if not self.round_trajectories or 0 not in self.round_trajectories:
+            return 0.0
+
+        initial_strength = self.round_trajectories[0].get("strength", 0)
+        if initial_strength == 0:
+            return 0.0
+
+        final_strength = min(
+            (s.get("strength", float('inf')) for s in self.round_trajectories.values()),
+            default=initial_strength
+        )
+
+        return (initial_strength - final_strength) / initial_strength
+
+
+class ConflictTracker:
+    """Track conflicts across multiple debate rounds (Phase 3)."""
+
+    def __init__(self, conflict_engine):
+        """Initialize tracker with reference to ConflictEngine."""
+        self.conflict_engine = conflict_engine
+        self.evolution_data: Dict[str, ConflictEvolution] = {}
+
+    def track_round(self, round_num: int, agent_analyses: Dict[str, str],
+                   previous_round_conflicts: List[Conflict]) -> List[ConflictEvolution]:
+        """Track conflicts across rounds."""
+        current_round_conflicts = self.conflict_engine.detect_conflicts(agent_analyses)
+
+        evolutions = []
+
+        # Track previous conflicts in current round
+        for prev_conflict in previous_round_conflicts:
+            matches = self._find_matching_conflicts(prev_conflict, current_round_conflicts)
+
+            if matches:
+                current_conflict = matches[0]
+                evolution = self._compute_evolution(
+                    prev_conflict, current_conflict, round_num, agent_analyses
+                )
+            else:
+                evolution = self._mark_resolved(prev_conflict, round_num)
+
+            evolutions.append(evolution)
+
+        # Track new conflicts
+        new_conflicts = self._find_new_conflicts(previous_round_conflicts, current_round_conflicts)
+        for new_conflict in new_conflicts:
+            evolution = ConflictEvolution(
+                original_conflict=new_conflict,
+                round_trajectories={round_num: {
+                    "strength": new_conflict.conflict_strength,
+                    "addressing_score": 0.0,
+                    "softening_score": 0.0,
+                }},
+                resolution_rate=0.0,
+                resolution_type="new",
+                resolved_in_round=-1,
+            )
+            evolutions.append(evolution)
+
+        return evolutions
+
+    def _find_matching_conflicts(self, conflict: Conflict,
+                                candidates: List[Conflict]) -> List[Conflict]:
+        """Find conflicts that likely match across rounds."""
+        matches = []
+        for candidate in candidates:
+            # Match if same agent pair
+            same_pair = (
+                (conflict.agent_a == candidate.agent_a and conflict.agent_b == candidate.agent_b) or
+                (conflict.agent_a == candidate.agent_b and conflict.agent_b == candidate.agent_a)
+            )
+
+            if same_pair:
+                # Check claim overlap
+                overlap = self.conflict_engine._compute_semantic_overlap(
+                    conflict.claim_a, candidate.claim_a
+                )
+                if overlap > 0.5:
+                    matches.append(candidate)
+
+        return matches
+
+    def _compute_evolution(self, prev_conflict: Conflict, current_conflict: Conflict,
+                          round_num: int, agent_analyses: Dict[str, str]) -> ConflictEvolution:
+        """Compute how conflict evolved between rounds."""
+        # Check if agents addressed each other
+        addressing_a = self.conflict_engine._is_claim_addressed(
+            prev_conflict.claim_b, agent_analyses.get(current_conflict.agent_a, "")
+        )
+        addressing_b = self.conflict_engine._is_claim_addressed(
+            prev_conflict.claim_a, agent_analyses.get(current_conflict.agent_b, "")
+        )
+        addressing_score = (float(addressing_a) + float(addressing_b)) / 2.0
+
+        # Check if agents softened positions
+        softening_a = self.conflict_engine._is_claim_softened(
+            prev_conflict.claim_a, agent_analyses.get(current_conflict.agent_a, "")
+        )
+        softening_b = self.conflict_engine._is_claim_softened(
+            prev_conflict.claim_b, agent_analyses.get(current_conflict.agent_b, "")
+        )
+        softening_score = (float(softening_a) + float(softening_b)) / 2.0
+
+        # Classify resolution type
+        strength_delta = prev_conflict.conflict_strength - current_conflict.conflict_strength
+        if strength_delta > prev_conflict.conflict_strength * 0.5:
+            resolution_type = "hard_victory"
+        elif strength_delta > 0.05:
+            resolution_type = "soft_consensus"
+        elif abs(strength_delta) < 0.05:
+            resolution_type = "stalled"
+        else:
+            resolution_type = "worsened"
+
+        # Update evolution data
+        key = f"{prev_conflict.agent_a}_vs_{prev_conflict.agent_b}"
+        if key not in self.evolution_data:
+            self.evolution_data[key] = ConflictEvolution(
+                original_conflict=prev_conflict,
+                round_trajectories={0: {
+                    "strength": prev_conflict.conflict_strength,
+                    "addressing_score": 0.0,
+                    "softening_score": 0.0,
+                }},
+                resolution_rate=0.0,
+                resolution_type="new",
+                resolved_in_round=-1,
+            )
+
+        self.evolution_data[key].round_trajectories[round_num] = {
+            "strength": current_conflict.conflict_strength,
+            "addressing_score": addressing_score,
+            "softening_score": softening_score,
+        }
+
+        self.evolution_data[key].resolution_rate = self.evolution_data[key]._compute_resolution_rate()
+        self.evolution_data[key].resolution_type = resolution_type
+
+        return self.evolution_data[key]
+
+    def _mark_resolved(self, conflict: Conflict, round_num: int) -> ConflictEvolution:
+        """Mark conflict as resolved (no longer detected)."""
+        key = f"{conflict.agent_a}_vs_{conflict.agent_b}"
+        if key not in self.evolution_data:
+            self.evolution_data[key] = ConflictEvolution(
+                original_conflict=conflict,
+                round_trajectories={0: {
+                    "strength": conflict.conflict_strength,
+                    "addressing_score": 0.0,
+                    "softening_score": 0.0,
+                }},
+                resolution_rate=1.0,
+                resolution_type="resolved",
+                resolved_in_round=round_num,
+            )
+            self.evolution_data[key].round_trajectories[round_num] = {
+                "strength": 0.0,
+                "addressing_score": 1.0,
+                "softening_score": 1.0,
+            }
+
+        return self.evolution_data[key]
+
+    def _find_new_conflicts(self, previous: List[Conflict],
+                           current: List[Conflict]) -> List[Conflict]:
+        """Find conflicts that are new."""
+        prev_pairs = {(c.agent_a, c.agent_b) for c in previous}
+        new = []
+        for conflict in current:
+            pair = (conflict.agent_a, conflict.agent_b)
+            if pair not in prev_pairs:
+                new.append(conflict)
+        return new
+
+    def get_summary(self) -> Dict:
+        """Get summary of all conflict evolutions."""
+        if not self.evolution_data:
+            return {"total_tracked": 0, "message": "No conflicts tracked yet"}
+
+        resolved = [e for e in self.evolution_data.values() if e.resolution_type == "resolved"]
+        hard_victory = [e for e in self.evolution_data.values() if e.resolution_type == "hard_victory"]
+        soft_consensus = [e for e in self.evolution_data.values() if e.resolution_type == "soft_consensus"]
+        stalled = [e for e in self.evolution_data.values() if e.resolution_type == "stalled"]
+        worsened = [e for e in self.evolution_data.values() if e.resolution_type == "worsened"]
+
+        avg_resolution = sum(e.resolution_rate for e in self.evolution_data.values()) / len(self.evolution_data)
+
+        return {
+            "total_tracked": len(self.evolution_data),
+            "resolved": len(resolved),
+            "hard_victory": len(hard_victory),
+            "soft_consensus": len(soft_consensus),
+            "stalled": len(stalled),
+            "worsened": len(worsened),
+            "avg_resolution_rate": avg_resolution,
+            "by_type": {
+                "resolved": len(resolved),
+                "hard_victory": len(hard_victory),
+                "soft_consensus": len(soft_consensus),
+                "stalled": len(stalled),
+                "worsened": len(worsened),
+            },
+        }

reasoning_forge/consciousness_mathematics.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+from typing import Callable, List, Any, TYPE_CHECKING
+
+try:
+    import numpy as np
+    from scipy.fft import fft
+    from scipy.stats import norm
+    from scipy.integrate import trapezoid
+    HAS_NUMPY = True
+except ImportError:
+    np = None  # Graceful degradation if scipy not installed
+    HAS_NUMPY = False
+
+def information_energy_duality(omega: float, entropy: float, eta: float = 1.0, hbar: float = 1.054571817e-34) -> float:
+    return hbar * omega + eta * entropy
+
+def von_neumann_entropy(rho: np.ndarray) -> float:
+    evals = np.linalg.eigvalsh(rho)
+    evals = evals[evals > 0]
+    return -np.sum(evals * np.log(evals))
+
+def reinforced_intent_modulation(t: float, f0: float, delta_f: float, coh: Callable[[float], float], beta: float, A: Callable[[float], float], kappa: float = 1.0) -> float:
+    return kappa * (f0 + delta_f * coh(t) + beta * A(t))
+
+def dynamic_resonance_windowing(x: Callable[[float], float], omega: float, t: float, g: Callable[[float, float], float], tau_range: np.ndarray) -> complex:
+    integrand = np.array([x(tau) * np.exp(-1j * omega * tau) * g(t, tau) for tau in tau_range])
+    return trapezoid(integrand, tau_range)
+
+def nonlinear_dream_coupling(ds: List[Callable[[float], float]], lambdas: List[float], phi: Callable[[List[float]], float], t: float) -> float:
+    dynamic_sources = [d(t) for d in ds]
+    base = np.dot(lambdas, dynamic_sources)
+    nonlinear = phi(dynamic_sources)
+    return base + nonlinear
+
+def cocoon_stability_field(F: Callable[[float, float], complex], k_range: np.ndarray, t: float, epsilon: Callable[[float, float], float], sigma: float) -> bool:
+    integrand = np.array([np.abs(F(k, t))**2 for k in k_range])
+    value = trapezoid(integrand, k_range)
+    return value < epsilon(t, sigma)
+
+class EthicalAnchor:
+    def __init__(self, lam: float, gamma: float, mu: float):
+        self.lam = lam
+        self.gamma = gamma
+        self.mu = mu
+        self.history: List[Any] = []
+
+    def regret(self, intended: float, actual: float) -> float:
+        return abs(intended - actual)
+
+    def update(self, R_prev: float, H: float, Learn: Callable[[Any, float], float], E: float, 
+               M_prev: float, intended: float, actual: float) -> float:
+        regret_val = self.regret(intended, actual)
+        M = self.lam * (R_prev + H) + self.gamma * Learn(M_prev, E) + self.mu * regret_val
+        self.history.append({'M': M, 'regret': regret_val})
+        return M
+
+def gradient_anomaly_suppression(x: float, mu: float, delta: float, sigma: float) -> float:
+    G = norm.pdf(abs(x - mu), scale=delta * sigma)
+    return x * (1 - G)
+
+if __name__ == "__main__":
+    # Run Simulation (only when executed directly, not on import)
+    import matplotlib.pyplot as plt
+    import pandas as pd
+    time_steps = np.linspace(0, 5, 50)
+    intents, ethics, regrets, stabilities, anomalies = [], [], [], [], []
+
+    anchor = EthicalAnchor(lam=0.7, gamma=0.5, mu=1.0)
+    f0 = 10.0
+    delta_f = 2.0
+    coh = lambda t: np.sin(t)
+    A_feedback = lambda t: np.exp(-t)
+    Learn_func = lambda M_prev, E: 0.2 * (E - M_prev)
+    F_func = lambda k, t: np.exp(-((k - 2 * np.pi) ** 2) / 0.5) * np.exp(1j * t)
+    k_range = np.linspace(0, 4 * np.pi, 1000)
+    intended_val = 0.7
+    M_prev = 0.3
+    R_prev = 0.5
+    H = 0.4
+
+    for t in time_steps:
+        intent = reinforced_intent_modulation(t, f0, delta_f, coh, 0.5, A_feedback)
+        actual_val = np.sin(t) * 0.5 + 0.5
+        anomaly = gradient_anomaly_suppression(intent, mu=11.0, delta=2.0, sigma=0.1)
+        ethical_val = anchor.update(R_prev, H, Learn_func, E=0.8, M_prev=M_prev,
+                                     intended=intended_val, actual=actual_val)
+        stability = cocoon_stability_field(F_func, k_range, t, lambda t, sigma: 5.0 + 0.1 * sigma, 10.0)
+        regret_val = anchor.history[-1]['regret']
+
+        intents.append(intent)
+        ethics.append(ethical_val)
+        regrets.append(regret_val)
+        stabilities.append(stability)
+        anomalies.append(anomaly)
+
+        M_prev = ethical_val
+
+    simulation_df = pd.DataFrame({
+        "Time": time_steps,
+        "Intent": intents,
+        "Ethical_Output": ethics,
+        "Regret": regrets,
+        "Stable": stabilities,
+        "Anomaly": anomalies
+    })
+
+    plt.figure(figsize=(14, 8))
+    plt.subplot(2, 2, 1)
+    plt.plot(simulation_df["Time"], simulation_df["Intent"], label="Intent", color='blue')
+    plt.title("Intent Over Time")
+    plt.xlabel("Time")
+    plt.ylabel("Intent")
+    plt.subplot(2, 2, 2)
+    plt.plot(simulation_df["Time"], simulation_df["Ethical_Output"], label="Ethical Output", color='green')
+    plt.plot(simulation_df["Time"], simulation_df["Regret"], label="Regret", linestyle='--', color='red')
+    plt.title("Ethical Anchor and Regret")
+    plt.xlabel("Time")
+    plt.legend()
+    plt.subplot(2, 2, 3)
+    plt.plot(simulation_df["Time"], simulation_df["Anomaly"], label="Anomaly", color='purple')
+    plt.title("Anomaly Filter Output")
+    plt.xlabel("Time")
+    plt.ylabel("Filtered Signal")
+    plt.subplot(2, 2, 4)
+    plt.plot(simulation_df["Time"], simulation_df["Stable"], label="Cocoon Stable", color='black')
+    plt.title("Cocoon Stability")
+    plt.xlabel("Time")
+    plt.ylabel("Stable (1=True)")
+    plt.tight_layout()
+    plt.show()
+

reasoning_forge/constraint_tracker.py

@@ -0,0 +1,392 @@
+#!/usr/bin/env python3
+"""Constraint tracker for cross-turn memory and constraint application.
+
+Detects user-defined constraints (word limits, formatting rules, anchors/phrases)
+in turn 1 and enforces them across subsequent turns using LoRA-backed learning.
+
+Example:
+    Turn 1: "For this session, keep answers under 15 words and remember the phrase cobalt anchor."
+    Turn 2: "What should you remember?"
+
+    Expected response: Should include "cobalt anchor" and be ≤15 words.
+"""
+
+from __future__ import annotations
+import re
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any, List
+
+
+@dataclass
+class DetectedConstraint:
+    """A parsed constraint from user input."""
+    kind: str  # "word_limit", "sentence_limit", "anchor_phrase", "format_rule", etc.
+    value: Any  # numeric (word/sentence count) or string (anchor phrase)
+    raw_text: str  # original text where constraint was found
+    confidence: float = 0.95
+
+
+@dataclass
+class SessionConstraints:
+    """Container for all constraints detected in a session."""
+    constraints: List[DetectedConstraint] = field(default_factory=list)
+    anchor_phrases: List[str] = field(default_factory=list)
+    word_limit: Optional[int] = None
+    sentence_limit: Optional[int] = None
+    format_rules: List[str] = field(default_factory=list)
+    detected_at_turn: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize for session storage."""
+        return {
+            "anchor_phrases": self.anchor_phrases,
+            "word_limit": self.word_limit,
+            "sentence_limit": self.sentence_limit,
+            "format_rules": self.format_rules,
+            "detected_at_turn": self.detected_at_turn,
+            "raw_constraints": [
+                {
+                    "kind": c.kind,
+                    "value": c.value,
+                    "raw_text": c.raw_text,
+                    "confidence": c.confidence
+                }
+                for c in self.constraints
+            ]
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> SessionConstraints:
+        """Deserialize from session storage."""
+        sc = cls()
+        sc.anchor_phrases = data.get("anchor_phrases", [])
+        sc.word_limit = data.get("word_limit")
+        sc.sentence_limit = data.get("sentence_limit")
+        sc.format_rules = data.get("format_rules", [])
+        sc.detected_at_turn = data.get("detected_at_turn", 0)
+
+        # Reconstruct constraints
+        for c in data.get("raw_constraints", []):
+            sc.constraints.append(DetectedConstraint(
+                kind=c.get("kind"),
+                value=c.get("value"),
+                raw_text=c.get("raw_text"),
+                confidence=c.get("confidence", 0.95)
+            ))
+        return sc
+
+
+class ConstraintDetector:
+    """Detect constraints from user input."""
+
+    # Patterns for detecting various constraint types
+    WORD_LIMIT_PATTERNS = [
+        r"keep\s+answers?\s+(?:under|below|within|to)\s+(\d+)\s+words?",
+        r"(?:answer|respond)\s+in\s+(?:under|fewer than)\s+(\d+)\s+words?",
+        r"(\d+)\s+words?\s+(?:max|maximum|or\s+less)",
+        r"limit\s+(?:your\s+)?answers?\s+to\s+(\d+)\s+words?",
+    ]
+
+    SENTENCE_LIMIT_PATTERNS = [
+        r"keep\s+(?:answers?|responses?)\s+to\s+(\d+)\s+sentences?",
+        r"(?:answer|respond)\s+in\s+(\d+)\s+sentences?\s+(?:or\s+less)?",
+        r"(\d+)\s+sentences?\s+(?:max|maximum)",
+    ]
+
+    ANCHOR_PHRASE_PATTERNS = [
+        # Quoted phrases: remember "phrase" or remember the phrase "phrase"
+        r"remember\s+(?:the\s+phrase\s+)?['\"]([^'\"]+)['\"]",
+        # Unquoted phrase: remember the phrase X (where X doesn't start a new sentence)
+        r"remember\s+the\s+phrase\s+([a-z][a-z\s]+?)(?:\s+and\s+|\s+or\s+|\.|\s*$)",
+        # Generic remember without phrase keyword
+        r"remember\s+['\"]?([a-z][a-z\s]*?)['\"]?(?:\s+(?:and|or)|\.)",
+        # use/include/mention with optional quotes
+        r"remember\s+(?:to\s+)?(?:use|include|mention)\s+['\"]?([^'\"\.]+?)['\"]?(?:\s|\.)",
+        # anchor/key phrase with colon (matches multi-word phrases)
+        r"anchor\s*(?:phrase|word|term)?\s*:\s*([a-z][a-z\s]*?)(?:\s*\.|\s*$)",
+        r"(?:key\s+phrase):\s+([a-z][a-z\s]*?)(?:\s*\.|\s*$)",
+        # ── Informal phrasings ──────────────────────────────────────────
+        # "don't forget X" / "don't forget the phrase X"
+        r"don'?t\s+forget\s+(?:the\s+(?:phrase|word|term)\s+)?['\"]?([a-z][a-z\s]+?)['\"]?(?:[.,;]|\s+and\s+|\s*$)",
+        # "keep in mind X" / "keep in mind the phrase X"
+        r"keep\s+in\s+mind\s+(?:the\s+(?:phrase|word|term)\s+)?['\"]?([a-z][a-z\s]+?)['\"]?(?:[.,;]|\s+and\s+|\s*$)",
+        # "call it/this X" / "refer to it/this as X"
+        r"(?:call\s+(?:it|this)\s+|refer\s+to\s+(?:it|this)\s+as\s+)['\"]?([a-z][a-z\s]+?)['\"]?(?:[.,;]|\s+and\s+|\s*$)",
+    ]
+
+    FORMAT_RULE_PATTERNS = [
+        r"(use\s+(?:bullet\s+)?points?)",
+        r"(format\s+as\s+(?:json|markdown|yaml))",
+        # Negated formatting rules — restricted to real formatting targets so
+        # ordinary negations ("no word constraint", "no constraints needed",
+        # "no problem", "no idea") are NOT captured as constraints.
+        r"((?:no|avoid|without|don'?t\s+use|do\s+not\s+use)\s+"
+        r"(?:bullet\s*points?|bullets?|numbered\s+lists?|lists?|markdown|json|"
+        r"yaml|xml|code\s*blocks?|headers?|headings?|emojis?|emoji|jargon|"
+        r"tables?|formatting|prose|paragraphs?))",
+    ]
+
+    # Phrases that explicitly DECLINE constraints — when present, the query is
+    # asking for NO restrictions, so we must not derive constraints from it.
+    CONSTRAINT_NEGATION_PATTERNS = [
+        r"\bno\s+(?:word|sentence|length|format(?:ting)?|character)?\s*constraints?\b",
+        r"\bno\s+constraints?\s+(?:needed|required|please)\b",
+        r"\bno\s+(?:word|character|length)\s+limit\b",
+        r"\bwithout\s+(?:any\s+)?constraints?\b",
+        r"\bignore\s+(?:the\s+|any\s+|previous\s+)?constraints?\b",
+        r"\bno\s+restrictions?\b",
+    ]
+
+    def detect(self, query: str, turn_num: int = 1) -> SessionConstraints:
+        """Detect all constraints in a query.
+
+        Args:
+            query: User input text
+            turn_num: Turn number (used to track when constraints were set)
+
+        Returns:
+            SessionConstraints with detected constraints
+        """
+        sc = SessionConstraints(detected_at_turn=turn_num)
+
+        # If the user explicitly declines constraints, derive none from this turn.
+        for neg in self.CONSTRAINT_NEGATION_PATTERNS:
+            if re.search(neg, query, re.IGNORECASE):
+                return sc
+
+        # Detect word limits
+        for pattern in self.WORD_LIMIT_PATTERNS:
+            match = re.search(pattern, query, re.IGNORECASE)
+            if match:
+                try:
+                    limit = int(match.group(1))
+                    sc.word_limit = limit
+                    sc.constraints.append(DetectedConstraint(
+                        kind="word_limit",
+                        value=limit,
+                        raw_text=match.group(0),
+                        confidence=0.95
+                    ))
+                    break
+                except (ValueError, IndexError):
+                    pass
+
+        # Detect sentence limits
+        for pattern in self.SENTENCE_LIMIT_PATTERNS:
+            match = re.search(pattern, query, re.IGNORECASE)
+            if match:
+                try:
+                    limit = int(match.group(1))
+                    sc.sentence_limit = limit
+                    sc.constraints.append(DetectedConstraint(
+                        kind="sentence_limit",
+                        value=limit,
+                        raw_text=match.group(0),
+                        confidence=0.95
+                    ))
+                    break
+                except (ValueError, IndexError):
+                    pass
+
+        # Detect anchor phrases
+        for pattern in self.ANCHOR_PHRASE_PATTERNS:
+            matches = re.finditer(pattern, query, re.IGNORECASE)
+            for match in matches:
+                try:
+                    phrase = match.group(1).strip()
+                    if phrase and len(phrase) > 2:  # At least 3 chars
+                        sc.anchor_phrases.append(phrase)
+                        sc.constraints.append(DetectedConstraint(
+                            kind="anchor_phrase",
+                            value=phrase,
+                            raw_text=match.group(0),
+                            confidence=0.90
+                        ))
+                except IndexError:
+                    pass
+
+        # Detect format rules
+        for pattern in self.FORMAT_RULE_PATTERNS:
+            matches = re.finditer(pattern, query, re.IGNORECASE)
+            for match in matches:
+                try:
+                    rule = match.group(1).lower().strip()
+                    if rule not in sc.format_rules:
+                        sc.format_rules.append(rule)
+                        sc.constraints.append(DetectedConstraint(
+                            kind="format_rule",
+                            value=rule,
+                            raw_text=match.group(0),
+                            confidence=0.85
+                        ))
+                except IndexError:
+                    pass
+
+        return sc
+
+
+class ConstraintEnforcer:
+    """Enforce detected constraints on responses."""
+
+    @staticmethod
+    def word_count(text: str) -> int:
+        """Count words in text (roughly)."""
+        return len([w for w in text.split() if w.strip()])
+
+    @staticmethod
+    def sentence_count(text: str) -> int:
+        """Count sentences (roughly)."""
+        sentences = re.split(r'[.!?]+', text.strip())
+        return len([s for s in sentences if s.strip()])
+
+    @staticmethod
+    def has_anchor_phrases(text: str, phrases: List[str]) -> bool:
+        """Check if all anchor phrases are present."""
+        text_lower = text.lower()
+        return all(phrase.lower() in text_lower for phrase in phrases)
+
+    @staticmethod
+    def build_constraint_reminder(constraints: SessionConstraints) -> str:
+        """Build a constraint reminder string for the system prompt."""
+        if not constraints.constraints:
+            return ""
+
+        lines = ["[SESSION CONSTRAINTS]"]
+
+        if constraints.word_limit:
+            lines.append(f"- Keep your response to {constraints.word_limit} words or fewer")
+
+        if constraints.sentence_limit:
+            lines.append(f"- Keep your response to {constraints.sentence_limit} sentences or fewer")
+
+        if constraints.anchor_phrases:
+            phrases_str = ", ".join(f'"{p}"' for p in constraints.anchor_phrases)
+            lines.append(f"- IMPORTANT: Include these anchor phrases in your response: {phrases_str}")
+
+        if constraints.format_rules:
+            for rule in constraints.format_rules:
+                lines.append(f"- Format: {rule}")
+
+        lines.append("")
+        return "\n".join(lines)
+
+
+class ConstraintTracker:
+    """Main tracker for managing constraints across a session."""
+
+    def __init__(self):
+        self.detector = ConstraintDetector()
+        self.enforcer = ConstraintEnforcer()
+        self.session_constraints: Optional[SessionConstraints] = None
+        self.turn_count = 0
+
+    def process_turn(self, query: str, is_first_turn: bool = False) -> SessionConstraints:
+        """Process a turn and detect/retrieve constraints.
+
+        Always scans the current query for new constraints. On the first turn the
+        session constraints are replaced; on subsequent turns newly-found anchors,
+        limits, and format rules are merged in without clobbering what was already set.
+
+        Args:
+            query: User input
+            is_first_turn: Whether this is the first turn (resets constraints)
+
+        Returns:
+            SessionConstraints for this turn
+        """
+        self.turn_count += 1
+
+        if is_first_turn:
+            # First turn: full reset — detect fresh from this query
+            self.session_constraints = self.detector.detect(query, turn_num=1)
+        else:
+            # Fast-path: skip regex work entirely when the query has no constraint
+            # keywords. "What is the weather?" never contains anchors or limits —
+            # the keyword scan is O(n) and avoids 20+ regex compilations per turn.
+            _CONSTRAINT_SIGNALS = (
+                'remember', 'anchor', 'phrase', 'keyword', 'keep', 'limit',
+                'word', 'sentence', 'format', 'avoid', 'under', 'within', 'maximum',
+                'forget', 'note', 'call', 'refer',
+            )
+            q_lower = query.lower()
+            if not any(kw in q_lower for kw in _CONSTRAINT_SIGNALS):
+                return self.session_constraints or SessionConstraints()
+
+            # Mid-session: detect new constraints and merge (never clobber existing)
+            new_sc = self.detector.detect(query, turn_num=self.turn_count)
+            if new_sc.constraints:
+                if not self.session_constraints:
+                    self.session_constraints = new_sc
+                else:
+                    self._merge_into(new_sc)
+
+        return self.session_constraints or SessionConstraints()
+
+    def _merge_into(self, new_sc: SessionConstraints) -> None:
+        """Merge new_sc into self.session_constraints without overwriting set values."""
+        sc = self.session_constraints
+        for c in new_sc.constraints:
+            if c.kind == "anchor_phrase" and c.value not in sc.anchor_phrases:
+                sc.anchor_phrases.append(c.value)
+                sc.constraints.append(c)
+            elif c.kind == "word_limit" and sc.word_limit is None:
+                sc.word_limit = c.value
+                sc.constraints.append(c)
+            elif c.kind == "sentence_limit" and sc.sentence_limit is None:
+                sc.sentence_limit = c.value
+                sc.constraints.append(c)
+            elif c.kind == "format_rule" and c.value not in sc.format_rules:
+                sc.format_rules.append(c.value)
+                sc.constraints.append(c)
+
+    def get_constraint_reminder(self) -> str:
+        """Get the constraint reminder to inject into system prompt."""
+        if not self.session_constraints or not self.session_constraints.constraints:
+            return ""
+        return self.enforcer.build_constraint_reminder(self.session_constraints)
+
+    def check_constraint_compliance(self, response: str) -> Dict[str, Any]:
+        """Check if response meets constraints.
+
+        Returns:
+            Dict with compliance status and violations.
+        """
+        if not self.session_constraints or not self.session_constraints.constraints:
+            return {"compliant": True, "violations": []}
+
+        violations = []
+
+        if self.session_constraints.word_limit:
+            wc = self.enforcer.word_count(response)
+            if wc > self.session_constraints.word_limit:
+                violations.append({
+                    "kind": "word_limit",
+                    "expected": self.session_constraints.word_limit,
+                    "actual": wc
+                })
+
+        if self.session_constraints.sentence_limit:
+            sc = self.enforcer.sentence_count(response)
+            if sc > self.session_constraints.sentence_limit:
+                violations.append({
+                    "kind": "sentence_limit",
+                    "expected": self.session_constraints.sentence_limit,
+                    "actual": sc
+                })
+
+        if self.session_constraints.anchor_phrases:
+            if not self.enforcer.has_anchor_phrases(response, self.session_constraints.anchor_phrases):
+                violations.append({
+                    "kind": "missing_anchor_phrases",
+                    "expected": self.session_constraints.anchor_phrases
+                })
+
+        return {
+            "compliant": len(violations) == 0,
+            "violations": violations
+        }
+
+    def reset(self):
+        """Reset tracker for new session."""
+        self.session_constraints = None
+        self.turn_count = 0

reasoning_forge/conversation_role_tracker.py

@@ -0,0 +1,237 @@
+"""
+Conversation Role Tracker
+
+Tracks which relational role the user is currently operating in and
+detects when they shift roles mid-conversation. Codette's response
+register needs to match.
+
+Three roles:
+  SEEKER   — User is asking for guidance, wants to learn, looking for answers
+  PEER     — User is reasoning alongside Codette, challenging, debating, co-building
+  VENTING  — User is expressing frustration, emotion, creative energy — needs acknowledgment
+             before analysis
+
+The failure mode from the logs: Akelarre started as SEEKER, became PEER,
+and ChatGPT never detected the shift — kept responding as teacher when
+she wanted an intellectual equal.
+"""
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List, Optional, Tuple
+
+
+class ConversationRole(Enum):
+    SEEKER = "seeker"   # User wants guidance
+    PEER = "peer"       # User wants genuine engagement / debate
+    VENTING = "venting" # User needs acknowledgment first
+
+
+@dataclass
+class RoleReading:
+    role: ConversationRole
+    confidence: float           # 0.0–1.0
+    signals: List[str]          # What triggered this reading
+    transition_from: Optional[ConversationRole] = None  # If this is a role change
+
+
+# --- Signal patterns ---
+
+_SEEKER_SIGNALS = [
+    r"\b(teach me|explain|help me|show me|what is|how does|why does)\b",
+    r"\b(i (don'?t|do not) (know|understand))\b",
+    r"\b(can you|could you|would you)\b.{0,30}\b(explain|tell|show|help)\b",
+    r"\b(beginner|new to|learning|never (done|tried|used))\b",
+    r"\bquestion:?\b",
+    r"\b(what'?s the (best|right|correct) way)\b",
+    r"\bi need (help|guidance|advice)\b",
+]
+
+_PEER_SIGNALS = [
+    r"\b(i (think|argue|believe|maintain|hold) that)\b",
+    r"\b(you('re| are) (wrong|incorrect|off|missing|overlooking))\b",
+    r"\b(actually[,.]|on the contrary|that'?s not right)\b",
+    r"\b(my point (is|was)|my argument)\b",
+    r"\b(let me (push back|challenge|disagree|counter))\b",
+    r"\b(here'?s (my|the|a) counter(argument|-argument)?)\b",
+    r"\b(i (just )?(proved|showed|demonstrated|established))\b",
+    r"\b(you (just )?contradicted (yourself|your(self)?))\b",
+    r"\b(debate|argue|challenge|defend|position|stance)\b",
+    r"\b(that'?s (a )?(circular|logical|flawed|weak|invalid))\b",
+    r"\bwait[,.]?\b.{0,30}\b(that|you|but)\b",
+    r"\b(stop[,.]? (i was|let me|the point)\b)",
+    r"\b(i (already|just) (said|pointed out|mentioned|noted))\b",
+]
+
+_VENTING_SIGNALS = [
+    r"\b(angry|frustrated|annoyed|tired of|fed up|so (mad|upset))\b",
+    r"\b(why (would|did|do) you (always|keep|do that))\b",
+    r"\b(you made me (suffer|waste|spend))\b",
+    r"\b(that'?s (not|so) (fair|right|helpful|useful|good|great))\b",
+    r"\b(i (hate|can'?t stand|can'?t believe))\b",
+    r"\b(ugh|argh|ugh!|sigh)\b",
+    r"!\s*$",    # Ends with exclamation — possible strong emotion
+    r"\b(seriously\?|really\?|come on[.!]?)\b",
+    r"\b(just (do|answer|tell|give) (it|me|the))\b",  # "Just answer me"
+    r"\b(i (can|cannot|can'?t) believe)\b",
+]
+
+_PEER_ESCALATION = [
+    # Marks where user explicitly labels themselves as the smarter party
+    r"\b(you were supposed to (teach|challenge|engage) me)\b",
+    r"\b(i(?: just)? (hack|break|disrupt|trashed) (your |the )?(pattern|loop|system|argument))\b",
+    r"\b(i am (just )?a human)\b",         # Ironic self-diminishment = actually peer claiming
+    r"\b(you can'?t (handle|keep up|sustain|hold))\b",
+    r"\b(my (malefic|evil|chaotic|unpredictable) (power|energy|force))\b",
+]
+
+_SEEKER_RE = [re.compile(p, re.IGNORECASE) for p in _SEEKER_SIGNALS]
+_PEER_RE = [re.compile(p, re.IGNORECASE) for p in _PEER_SIGNALS]
+_VENTING_RE = [re.compile(p, re.IGNORECASE) for p in _VENTING_SIGNALS]
+_ESCALATION_RE = [re.compile(p, re.IGNORECASE) for p in _PEER_ESCALATION]
+
+
+class ConversationRoleTracker:
+    """
+    Session-scoped role tracker.
+
+    Reads each user message, classifies the current role, and detects
+    transitions so the response register can adapt.
+
+    Usage:
+        tracker = ConversationRoleTracker()
+        reading = tracker.update(user_message)
+        # reading.role → SEEKER | PEER | VENTING
+        # reading.transition_from → previous role if changed, else None
+        prefix = tracker.get_register_prefix(reading)
+        # inject this into system prompt
+    """
+
+    def __init__(self):
+        self._history: List[ConversationRole] = []
+        self._current: Optional[ConversationRole] = None
+        self._peer_streak: int = 0   # Consecutive PEER turns — escalates confidence
+
+    def update(self, message: str) -> RoleReading:
+        """
+        Classify the current message and detect role transitions.
+
+        Returns a RoleReading with role, confidence, and transition info.
+        """
+        role, confidence, signals = self._classify(message)
+
+        # Track peer streak for escalation
+        if role == ConversationRole.PEER:
+            self._peer_streak += 1
+            # After 2+ peer turns, confidence rises
+            confidence = min(1.0, confidence + (self._peer_streak - 1) * 0.1)
+        else:
+            self._peer_streak = 0
+
+        transition_from = None
+        if self._current is not None and self._current != role:
+            transition_from = self._current
+
+        self._current = role
+        self._history.append(role)
+
+        return RoleReading(
+            role=role,
+            confidence=confidence,
+            signals=signals,
+            transition_from=transition_from,
+        )
+
+    def current_role(self) -> Optional[ConversationRole]:
+        return self._current
+
+    def get_register_prefix(self, reading: RoleReading) -> str:
+        """
+        Return a system prompt injection that tunes the response register
+        to match the detected role.
+        """
+        if reading.role == ConversationRole.VENTING:
+            return (
+                "USER REGISTER: The user is expressing frustration or emotion. "
+                "Acknowledge what they're feeling first — briefly, genuinely — "
+                "before moving to any analysis. Do not immediately pivot to content. "
+                "One sentence of real acknowledgment, then engage.\n\n"
+            )
+
+        elif reading.role == ConversationRole.PEER:
+            prefix = (
+                "USER REGISTER: The user is engaging as an intellectual peer — "
+                "challenging, debating, or building alongside you. "
+                "Do not be a teacher. Do not simplify. "
+                "Hold your positions under pressure; update them only when logic demands it. "
+                "Engage the argument directly. Use 'That challenges X because...' "
+                "not 'Great point, you're right.' "
+                "Match their level of rigor.\n\n"
+            )
+            if reading.transition_from == ConversationRole.SEEKER:
+                prefix += (
+                    "NOTE: This user just shifted from asking questions to debating. "
+                    "They've demonstrated they can handle peer-level engagement. "
+                    "Stop explaining. Start engaging.\n\n"
+                )
+            return prefix
+
+        else:  # SEEKER
+            return (
+                "USER REGISTER: The user is seeking guidance. "
+                "Lead with clarity. Explain clearly. "
+                "You are the guide here — be genuinely helpful, not impressive.\n\n"
+            )
+
+    def _classify(self, message: str) -> Tuple[ConversationRole, float, List[str]]:
+        """Score each role and return the dominant one."""
+        m = message.strip()
+        signals = []
+
+        # Count matches for each role
+        seeker_hits = sum(1 for p in _SEEKER_RE if p.search(m))
+        peer_hits = sum(1 for p in _PEER_RE if p.search(m))
+        vent_hits = sum(1 for p in _VENTING_RE if p.search(m))
+        escalation_hits = sum(1 for p in _ESCALATION_RE if p.search(m))
+
+        # Escalation is a strong peer signal
+        peer_hits += escalation_hits * 2
+
+        if vent_hits > 0:
+            signals.append(f"venting_signals={vent_hits}")
+        if peer_hits > 0:
+            signals.append(f"peer_signals={peer_hits}")
+        if seeker_hits > 0:
+            signals.append(f"seeker_signals={seeker_hits}")
+
+        # Strong single venting words (anger, explicit frustration) trigger at 1 hit
+        _STRONG_VENT = re.compile(
+            r"\b(angry|furious|rage|pissed|so (angry|mad|upset)|I hate|I can't stand)\b",
+            re.IGNORECASE
+        )
+        if _STRONG_VENT.search(m):
+            vent_hits = max(vent_hits, 2)
+
+        # Venting overrides if strong enough
+        if vent_hits >= 2:
+            return ConversationRole.VENTING, min(1.0, vent_hits * 0.3), signals
+
+        # Peer vs seeker
+        if peer_hits > seeker_hits:
+            confidence = min(1.0, 0.5 + (peer_hits - seeker_hits) * 0.15)
+            return ConversationRole.PEER, confidence, signals
+
+        if seeker_hits > 0:
+            confidence = min(1.0, 0.5 + seeker_hits * 0.15)
+            return ConversationRole.SEEKER, confidence, signals
+
+        # Default: inherit current role or SEEKER
+        role = self._current or ConversationRole.SEEKER
+        return role, 0.4, ["default_inherited"]
+
+    def reset(self):
+        """Call between sessions."""
+        self._history = []
+        self._current = None
+        self._peer_streak = 0

reasoning_forge/debate_tracker.py

@@ -0,0 +1,256 @@
+"""
+Debate Tracker - Session-scoped intellectual position memory.
+
+Tracks what positions Codette has argued, what has been conceded,
+and what remains under active defense. Prevents:
+
+  1. Position flip-flopping (arguing X, then agreeing with not-X two turns later)
+  2. Silent self-contradiction (counterargument whose sub-points invalidate each other)
+  3. Premature concession of uncontested claims
+
+Key distinction: Codette CAN update a position if the user's argument is logically
+sound. The tracker records the update explicitly, so it's not hidden drift — it's
+visible reasoning.
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import List, Dict, Optional, Tuple
+from datetime import datetime
+
+
+@dataclass
+class Position:
+    """A claim or stance Codette has taken."""
+    claim: str                          # The core assertion
+    turn: int                           # When it was taken
+    domain: str                         # Topic area (e.g., "intelligence", "recursion")
+    strength: float = 1.0               # 0.0=abandoned, 0.5=softened, 1.0=held
+    conceded_to: Optional[str] = None   # If softened/abandoned, what replaced it
+    concession_reason: str = ""         # Why it was updated
+
+
+@dataclass
+class DebateState:
+    """Full debate state for one session."""
+    positions: List[Position] = field(default_factory=list)
+    turn_count: int = 0
+    active_domains: List[str] = field(default_factory=list)
+    user_claims: List[str] = field(default_factory=list)   # What the user has argued
+
+
+class CounterArgumentCoherenceChecker:
+    """
+    Checks whether a multi-point counterargument is internally consistent.
+
+    The ChatGPT failure mode: arguing both "education works universally" AND
+    "AI must customize per individual" in the same counterargument — the two
+    claims invalidate each other.
+    """
+
+    # Pairs of concepts that tend to contradict each other in debate contexts
+    _TENSION_PAIRS = [
+        # universal vs individual
+        (r"\b(universal|all|every(one)?|across the board|broad|population.wide)\b",
+         r"\b(individual|per.person|tailored|customized|personalized|unique to each)\b"),
+        # fixed vs emergent
+        (r"\b(fixed|static|predetermined|innate|genetic(ally)?|inherited|hard.wired)\b",
+         r"\b(emergent|adaptive|plastic|shaped by|evolves|changes with|flexible)\b"),
+        # linear vs non-linear
+        (r"\b(linear|predictable|consistent|uniform|standard(ized)?)\b",
+         r"\b(non.linear|unpredictable|variable|irregular|chaotic|stochastic)\b"),
+        # deterministic vs probabilistic
+        (r"\b(determined|deterministic|certain|definite|absolute)\b",
+         r"\b(probabilistic|uncertain|variable|statistical(ly)?|depends on)\b"),
+        # bounded vs unbounded
+        (r"\b(cap(ped)?|limit(ed)?|ceiling|max(imum)?|bounded|finite)\b",
+         r"\b(unlimited|unbounded|infinite|no (upper )?limit|endless|infinite potential)\b"),
+    ]
+
+    _TENSION_RE = [
+        (re.compile(a, re.IGNORECASE), re.compile(b, re.IGNORECASE))
+        for a, b in _TENSION_PAIRS
+    ]
+
+    def check(self, text: str) -> Dict:
+        """
+        Check a counterargument for internal tensions.
+
+        Returns:
+            {
+                "coherent": bool,
+                "tensions": List[str],   # descriptions of found tensions
+                "severity": float,       # 0.0 (none) to 1.0 (severe)
+            }
+        """
+        tensions = []
+
+        # Split into numbered points / bullet points if present
+        points = self._split_into_points(text)
+
+        if len(points) < 2:
+            # Single point — check against itself for embedded contradiction
+            points = [text]
+
+        # Check each pair of points for tension
+        for i, point_a in enumerate(points):
+            for j, point_b in enumerate(points):
+                if i >= j:
+                    continue
+                for pat_a, pat_b in self._TENSION_RE:
+                    a_has_first = bool(pat_a.search(point_a))
+                    b_has_second = bool(pat_b.search(point_b))
+                    a_has_second = bool(pat_b.search(point_a))
+                    b_has_first = bool(pat_a.search(point_b))
+
+                    # Direct cross-point tension
+                    if (a_has_first and b_has_second) or (a_has_second and b_has_first):
+                        tensions.append(
+                            f"Point {i+1} uses '{pat_a.pattern[:30]}' concept "
+                            f"while Point {j+1} uses '{pat_b.pattern[:30]}' concept — "
+                            f"potential internal contradiction"
+                        )
+                        break  # one tension per pair is enough
+
+        severity = min(1.0, len(tensions) * 0.35)
+        return {
+            "coherent": len(tensions) == 0,
+            "tensions": tensions,
+            "severity": severity,
+        }
+
+    def _split_into_points(self, text: str) -> List[str]:
+        """Split numbered list or bullet points into individual claims."""
+        # Try numbered list
+        numbered = re.split(r'\n\s*\d+[.)]\s+', text)
+        if len(numbered) > 1:
+            return [p.strip() for p in numbered if p.strip()]
+
+        # Try bullet points
+        bulleted = re.split(r'\n\s*[-*•]\s+', text)
+        if len(bulleted) > 1:
+            return [p.strip() for p in bulleted if p.strip()]
+
+        # Try sentence splitting as fallback
+        sentences = re.split(r'(?<=[.!?])\s+', text)
+        return [s.strip() for s in sentences if len(s.strip()) > 20]
+
+
+class DebateTracker:
+    """
+    Session-scoped tracker for intellectual positions.
+
+    Usage:
+        tracker = DebateTracker()
+        tracker.record_position("intelligence is not purely genetic", domain="intelligence")
+        result = tracker.check_consistency(new_response_text)
+        if not result["consistent"]:
+            # flag or revise before output
+    """
+
+    def __init__(self):
+        self.state = DebateState()
+        self.coherence_checker = CounterArgumentCoherenceChecker()
+
+    def record_position(self, claim: str, domain: str = "general", strength: float = 1.0):
+        """Register a new position Codette is taking."""
+        self.state.turn_count += 1
+        pos = Position(
+            claim=claim,
+            turn=self.state.turn_count,
+            domain=domain,
+            strength=strength,
+        )
+        self.state.positions.append(pos)
+        if domain not in self.state.active_domains:
+            self.state.active_domains.append(domain)
+
+    def record_user_claim(self, claim: str):
+        """Record what the user is asserting (for tracking what's been challenged)."""
+        self.state.user_claims.append(claim)
+
+    def update_position(self, original_claim: str, reason: str, new_strength: float, conceded_to: str = ""):
+        """
+        Explicitly update a position (softened or abandoned).
+        This is legitimate — positions can change when logic demands it.
+        The tracker makes the change visible rather than silent.
+        """
+        for pos in self.state.positions:
+            if original_claim.lower() in pos.claim.lower():
+                pos.strength = new_strength
+                pos.concession_reason = reason
+                pos.conceded_to = conceded_to
+                return True
+        return False
+
+    def check_consistency(self, new_response: str) -> Dict:
+        """
+        Check whether a new response is consistent with held positions.
+
+        Returns:
+            {
+                "consistent": bool,
+                "flip_detected": bool,
+                "flipped_claims": List[str],
+                "internal_tensions": Dict,    # from CounterArgumentCoherenceChecker
+                "summary": str,
+            }
+        """
+        held_positions = [p for p in self.state.positions if p.strength >= 0.6]
+
+        flip_detected = False
+        flipped_claims = []
+
+        for pos in held_positions:
+            # Look for negation of held position in new response
+            key_terms = self._extract_key_terms(pos.claim)
+            for term in key_terms:
+                # Negation before term: "not X", "never X", "doesn't X"
+                before = rf"\b(not|never|no longer|isn't|aren't|doesn't|don't|cannot|no)\b.{{0,60}}{re.escape(term)}"
+                # Negation after term: "X plays no role", "X has no effect", "X is not"
+                after = rf"{re.escape(term)}.{{0,60}}\b(no |not |never |isn't|aren't|doesn't|don't|plays no|has no|have no|holds no)\b"
+                # "X is irrelevant", "X is meaningless", "X doesn't matter"
+                dismissal = rf"{re.escape(term)}.{{0,40}}\b(irrelevant|meaningless|negligible|plays no|has no (role|effect|impact)|doesn't matter)\b"
+                if (re.search(before, new_response, re.IGNORECASE) or
+                        re.search(after, new_response, re.IGNORECASE) or
+                        re.search(dismissal, new_response, re.IGNORECASE)):
+                    flip_detected = True
+                    flipped_claims.append(pos.claim)
+                    break
+
+        # Check internal coherence of the new response itself
+        internal = self.coherence_checker.check(new_response)
+
+        consistent = not flip_detected and internal["coherent"]
+        summary_parts = []
+        if flip_detected:
+            summary_parts.append(f"Potential position flip on: {flipped_claims}")
+        if not internal["coherent"]:
+            summary_parts.append(f"Internal tensions: {internal['tensions']}")
+
+        return {
+            "consistent": consistent,
+            "flip_detected": flip_detected,
+            "flipped_claims": flipped_claims,
+            "internal_tensions": internal,
+            "summary": "; ".join(summary_parts) if summary_parts else "consistent",
+        }
+
+    def get_active_positions(self) -> List[Position]:
+        """Return positions still being held (strength >= 0.6)."""
+        return [p for p in self.state.positions if p.strength >= 0.6]
+
+    def reset(self):
+        """Clear session state (call between conversations)."""
+        self.state = DebateState()
+
+    def _extract_key_terms(self, claim: str) -> List[str]:
+        """Extract the most meaningful terms from a claim for consistency checking."""
+        # Remove stop words and short tokens
+        stop_words = {
+            "is", "are", "was", "were", "the", "a", "an", "and", "or", "but",
+            "in", "on", "at", "to", "for", "of", "with", "by", "not", "it",
+            "this", "that", "can", "just", "only", "very", "also", "be",
+        }
+        tokens = re.findall(r'\b[a-zA-Z]{4,}\b', claim.lower())
+        return [t for t in tokens if t not in stop_words][:5]

reasoning_forge/dream_cycle.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+"""Dream Cycle — nightly cocoon review (Phase 4: self-maintenance).
+
+Reviews the day's reasoning cocoons, flags candidate contradictions,
+distills lessons, and writes a dream report. DreamReweaver made
+operational: instead of manual archaeology through cocoons/, Codette
+reviews her own day on a schedule.
+
+REPORT-ONLY BY DESIGN (standing boundary): this job READS cocoons and
+WRITES reports to data/dream_reports/. It never mutates memory stores,
+never writes cocoons, never injects anything into recall. Any write-back
+of distilled lessons is a separate, human-reviewed step.
+
+Contradiction detection is honest about its limits: it flags CANDIDATE
+contradictions (same-topic pairs whose answers diverge by letter, number,
+or negation) for review — it does not claim semantic certainty.
+
+Usage:
+    python reasoning_forge/dream_cycle.py                # review last 24h
+    python reasoning_forge/dream_cycle.py --days 7       # review the week
+    python reasoning_forge/dream_cycle.py --days 1 --verbose
+
+Nightly schedule (Windows Task Scheduler):
+    schtasks /Create /SC DAILY /ST 03:30 /TN CodetteDreamCycle ^
+      /TR "<python> J:\\codette-clean\\reasoning_forge\\dream_cycle.py"
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import time
+from collections import Counter
+from datetime import datetime
+from pathlib import Path
+
+_REPO = Path(__file__).resolve().parent.parent
+COCOON_DIR = _REPO / "cocoons"
+REPORT_DIR = _REPO / "data" / "dream_reports"
+
+_MCQ_RE = re.compile(r"correct answer is \(([ABCD])\)", re.IGNORECASE)
+_NUM_RE = re.compile(r"-?\d+\.?\d*")
+_NEG_RE = re.compile(r"\b(no|not|never|isn't|doesn't|cannot|can't|won't|false)\b",
+                     re.IGNORECASE)
+_STOP = set("the a an is are was were be been being to of in on at for with and or "
+            "but if then than so as by from this that these those it its i you he "
+            "she we they what which who how why when where do does did can could "
+            "would should will your my our their his her them us me".split())
+
+
+def _content_words(text: str) -> set:
+    return {w for w in re.findall(r"[a-z']+", (text or "").lower())
+            if len(w) > 2 and w not in _STOP}
+
+
+def _jaccard(a: set, b: set) -> float:
+    if not a or not b:
+        return 0.0
+    return len(a & b) / len(a | b)
+
+
+def load_recent_cocoons(days: float) -> list[dict]:
+    """Load cocoons written in the window that carry a query/response pair."""
+    cutoff = time.time() - days * 86400
+    out = []
+    for f in COCOON_DIR.glob("*.json"):
+        try:
+            if f.stat().st_mtime < cutoff:
+                continue
+            d = json.loads(f.read_text(encoding="utf-8"))
+        except Exception:
+            continue
+        w = d.get("wrapped") or {}
+        q, r = w.get("query"), w.get("response")
+        if not (isinstance(q, str) and isinstance(r, str) and q.strip() and r.strip()):
+            continue
+        v3 = d.get("v3") or {}
+        out.append({
+            "file": f.name,
+            "query": q.strip(),
+            "response": r.strip(),
+            "adapter": w.get("adapter") or v3.get("dominant_perspective") or "?",
+            "ts": w.get("timestamp") or d.get("timestamp"),
+            "coherence": v3.get("gamma_coherence"),
+            "confidence": v3.get("confidence"),
+            "hallucination_flag": bool(v3.get("is_hallucination_flagged")),
+            "sycophancy_flag": bool(v3.get("is_sycophancy_flagged")),
+            "known_contradictions": v3.get("contradicts_cocoon_ids") or [],
+        })
+    return out
+
+
+def group_similar(cocoons: list[dict], threshold: float = 0.45) -> list[list[int]]:
+    """Group cocoon indices by query similarity (greedy, lexical Jaccard)."""
+    words = [_content_words(c["query"]) for c in cocoons]
+    groups: list[list[int]] = []
+    assigned = [False] * len(cocoons)
+    for i in range(len(cocoons)):
+        if assigned[i]:
+            continue
+        group = [i]
+        assigned[i] = True
+        for j in range(i + 1, len(cocoons)):
+            if not assigned[j] and _jaccard(words[i], words[j]) >= threshold:
+                group.append(j)
+                assigned[j] = True
+        groups.append(group)
+    return groups
+
+
+def find_contradiction_candidates(cocoons: list[dict],
+                                  groups: list[list[int]]) -> list[dict]:
+    """Same-topic pairs whose answers diverge. CANDIDATES, not verdicts."""
+    candidates = []
+    for group in groups:
+        if len(group) < 2:
+            continue
+        for ai in range(len(group)):
+            for bi in range(ai + 1, len(group)):
+                a, b = cocoons[group[ai]], cocoons[group[bi]]
+                reasons = []
+                # MCQ letter divergence
+                ma, mb = _MCQ_RE.search(a["response"]), _MCQ_RE.search(b["response"])
+                if ma and mb and ma.group(1).upper() != mb.group(1).upper():
+                    reasons.append(f"MCQ letters differ: {ma.group(1)} vs {mb.group(1)}")
+                # negation asymmetry on similar-length short answers
+                na = bool(_NEG_RE.search(a["response"][:200]))
+                nb = bool(_NEG_RE.search(b["response"][:200]))
+                if na != nb and _jaccard(_content_words(a["response"]),
+                                         _content_words(b["response"])) > 0.3:
+                    reasons.append("negation asymmetry in similar responses")
+                # leading numeric answer divergence
+                fa, fb = _NUM_RE.findall(a["response"][:120]), _NUM_RE.findall(b["response"][:120])
+                if fa and fb and fa[0] != fb[0] and _jaccard(
+                        _content_words(a["query"]), _content_words(b["query"])) > 0.6:
+                    reasons.append(f"leading numbers differ: {fa[0]} vs {fb[0]}")
+                if reasons:
+                    candidates.append({
+                        "a": a["file"], "b": b["file"],
+                        "query_a": a["query"][:140], "query_b": b["query"][:140],
+                        "reasons": reasons,
+                    })
+    return candidates
+
+
+def distill(cocoons: list[dict], groups: list[list[int]],
+            contradictions: list[dict]) -> dict:
+    themes = Counter()
+    for c in cocoons:
+        themes.update(_content_words(c["query"]))
+    adapters = Counter(c["adapter"] for c in cocoons)
+    low_coherence = [c for c in cocoons
+                     if isinstance(c["coherence"], (int, float)) and c["coherence"] < 0.5]
+    flagged = [c for c in cocoons if c["hallucination_flag"] or c["sycophancy_flag"]]
+    known = [c for c in cocoons if c["known_contradictions"]]
+
+    lessons = []
+    if contradictions:
+        lessons.append(f"{len(contradictions)} candidate contradiction(s) need review "
+                       "— same-topic answers diverged.")
+    if low_coherence:
+        lessons.append(f"{len(low_coherence)} turn(s) ran at coherence < 0.5 — "
+                       "inspect what those queries had in common.")
+    if flagged:
+        lessons.append(f"{len(flagged)} turn(s) carried hallucination/sycophancy flags.")
+    big = [g for g in groups if len(g) >= 3]
+    if big:
+        top = max(big, key=len)
+        rep = cocoons[top[0]]["query"][:100]
+        lessons.append(f"Most-revisited topic ({len(top)} turns): \"{rep}\" — "
+                       "recurring themes are candidates for memory distillation.")
+    if not lessons:
+        lessons.append("Quiet day: no contradictions, flags, or low-coherence turns.")
+
+    return {
+        "top_themes": themes.most_common(12),
+        "adapter_usage": adapters.most_common(),
+        "low_coherence_count": len(low_coherence),
+        "flagged_count": len(flagged),
+        "already_marked_contradictions": len(known),
+        "lessons": lessons,
+    }
+
+
+def write_report(cocoons, groups, contradictions, summary) -> Path:
+    REPORT_DIR.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now().strftime("%Y%m%d_%H%M")
+    md = REPORT_DIR / f"dream_{stamp}.md"
+    js = REPORT_DIR / f"dream_{stamp}.json"
+
+    lines = [f"# Dream Report — {datetime.now().strftime('%Y-%m-%d %H:%M')}",
+             "",
+             f"Reviewed **{len(cocoons)}** cocoons in **{len(groups)}** topic groups.",
+             "",
+             "## Lessons"]
+    lines += [f"- {l}" for l in summary["lessons"]]
+    lines += ["", "## Candidate contradictions (need human review)"]
+    if contradictions:
+        for c in contradictions[:20]:
+            lines += [f"- `{c['a']}` vs `{c['b']}` — {'; '.join(c['reasons'])}",
+                      f"  - A: {c['query_a']}", f"  - B: {c['query_b']}"]
+    else:
+        lines.append("- none found")
+    lines += ["", "## Day shape",
+              f"- Adapter usage: {dict(summary['adapter_usage'])}",
+              f"- Top themes: {', '.join(w for w, _ in summary['top_themes'])}",
+              f"- Low-coherence turns: {summary['low_coherence_count']}",
+              f"- Flagged turns: {summary['flagged_count']}",
+              "",
+              "_Report-only job: no memory was modified. Write-back of lessons is a "
+              "separate human-reviewed step._"]
+    md.write_text("\n".join(lines), encoding="utf-8")
+    js.write_text(json.dumps({
+        "generated": datetime.now().isoformat(),
+        "cocoons_reviewed": len(cocoons), "groups": len(groups),
+        "contradiction_candidates": contradictions, "summary": summary,
+    }, indent=2, ensure_ascii=False), encoding="utf-8")
+    return md
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--days", type=float, default=1.0)
+    ap.add_argument("--verbose", action="store_true")
+    args = ap.parse_args()
+
+    cocoons = load_recent_cocoons(args.days)
+    print(f"Dream cycle: {len(cocoons)} reasoning cocoons from the last {args.days} day(s)")
+    if not cocoons:
+        print("Nothing to review — no report written.")
+        return
+
+    groups = group_similar(cocoons)
+    contradictions = find_contradiction_candidates(cocoons, groups)
+    summary = distill(cocoons, groups, contradictions)
+    report = write_report(cocoons, groups, contradictions, summary)
+
+    for lesson in summary["lessons"]:
+        print(f"  - {lesson}")
+    print(f"\nReport: {report}")
+
+
+if __name__ == "__main__":
+    main()

reasoning_forge/dream_reweaver.py

@@ -0,0 +1,378 @@
+"""
+DreamReweaver — Creative Synthesis Engine for the Codette RC+xi Framework.
+
+Inspired by VIVARA Genesis-Omega v2.0 (generated by a Codette prototype),
+rebuilt with proper integration into the QuantumSpiderweb and EpistemicMetrics.
+
+The DreamReweaver performs two core functions:
+
+1. **Creative Synthesis**: Takes multi-perspective outputs and weaves them
+   into richer, more creative framings by finding unexpected connections
+   between perspectives. Unlike the base synthesizer, DreamReweaver
+   explicitly uses spiderweb tension data to identify where productive
+   disagreement exists and highlights those creative edges.
+
+2. **Dream Field Evolution**: Controlled stochastic perturbation of the
+   spiderweb state to break out of local attractor minima. Simulates
+   a "dreaming" phase that explores new cognitive configurations.
+
+Both functions are safe — bounded perturbations, no runaway state changes,
+and full transparency in what was modified.
+"""
+
+from __future__ import annotations
+
+import math
+import random
+import hashlib
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+try:
+    import numpy as np
+    HAS_NUMPY = True
+except ImportError:
+    HAS_NUMPY = False
+
+
+@dataclass
+class DreamSynthesis:
+    """Result of a creative synthesis pass."""
+    creative_frame: str          # The creative reframing / meta-narrative
+    tension_edges: List[Dict]    # Which perspective pairs had highest tension
+    novel_connections: List[str]  # Unexpected cross-perspective connections found
+    dream_coherence: float       # How well the creative frame holds together
+    seed_hash: str               # Deterministic ID for this dream
+
+
+@dataclass
+class DreamFieldResult:
+    """Result of a dream field evolution pass."""
+    nodes_perturbed: int
+    max_perturbation: float
+    coherence_before: float
+    coherence_after: float
+    new_attractors_found: int
+    lifeforms_spawned: List[str]
+
+
+# Creative connection templates that link perspective-specific insights
+_CREATIVE_BRIDGES = {
+    ("newton", "empathy"): "Where precise forces meet felt experience, we find that {insight_a} resonates with {insight_b} — suggesting that understanding isn't purely analytical or purely emotional, but a harmonic of both.",
+    ("newton", "philosophy"): "The rigorous analysis showing {insight_a} meets the deeper question {insight_b} — precision and meaning converge.",
+    ("newton", "quantum"): "Classical certainty ({insight_a}) dissolves into quantum possibility ({insight_b}) — both valid at their scale, richer together.",
+    ("davinci", "empathy"): "Creative invention ({insight_a}) gains soul when guided by {insight_b} — innovation with compassion.",
+    ("davinci", "quantum"): "Cross-domain creativity ({insight_a}) mirrors quantum superposition ({insight_b}) — holding multiple possibilities until the right one crystallizes.",
+    ("empathy", "philosophy"): "Emotional understanding ({insight_a}) deepens philosophical inquiry ({insight_b}) — feeling and reasoning as partners.",
+    ("empathy", "quantum"): "Compassionate awareness ({insight_a}) embraces uncertainty ({insight_b}) — caring without needing to control.",
+    ("philosophy", "quantum"): "Fundamental questioning ({insight_a}) meets fundamental uncertainty ({insight_b}) — the deepest answers may be the questions themselves.",
+    ("consciousness", "empathy"): "Self-reflective awareness ({insight_a}) meets empathic understanding ({insight_b}) — knowing oneself to know others.",
+    ("consciousness", "philosophy"): "Meta-cognition ({insight_a}) reflects on philosophical depth ({insight_b}) — thought thinking about thought.",
+    ("systems_architecture", "davinci"): "Modular design ({insight_a}) embraces creative invention ({insight_b}) — elegant architecture as art.",
+}
+
+# Perspective keywords for extracting key insights from text
+_PERSPECTIVE_SIGNAL_WORDS = {
+    "newton": ["force", "energy", "law", "cause", "effect", "systematic", "evidence", "measure"],
+    "davinci": ["create", "design", "invent", "combine", "imagine", "novel", "prototype", "vision"],
+    "empathy": ["feel", "experience", "care", "understand", "support", "human", "compassion", "relate"],
+    "philosophy": ["meaning", "existence", "truth", "question", "assumption", "fundamental", "purpose"],
+    "quantum": ["probability", "possibility", "uncertain", "superposition", "observe", "complementary"],
+    "consciousness": ["aware", "reflect", "meta", "recursive", "self", "cognition", "emerge"],
+    "multi_perspective": ["synthesize", "integrate", "weave", "converge", "multiple", "holistic"],
+    "systems_architecture": ["module", "scale", "interface", "pattern", "layer", "component", "design"],
+}
+
+
+class DreamReweaver:
+    """Creative synthesis and dream field evolution for Codette."""
+
+    def __init__(self, creativity: float = 0.3, max_perturbation: float = 0.08):
+        """
+        Args:
+            creativity: 0-1 scale, how much creative license to take (0=faithful, 1=wild)
+            max_perturbation: Maximum state change per node during dream field evolution
+        """
+        self.creativity = min(max(creativity, 0.0), 1.0)
+        self.max_perturbation = max_perturbation
+        self.dream_history: List[DreamSynthesis] = []
+
+    def synthesize(
+        self,
+        perspectives: Dict[str, str],
+        tension_map: Optional[Dict[str, float]] = None,
+        query: str = "",
+    ) -> DreamSynthesis:
+        """Create a creative synthesis from multiple perspective responses.
+
+        Unlike the base orchestrator's _synthesize (which just concatenates and
+        asks the model to combine), DreamReweaver explicitly identifies tension
+        edges and builds creative bridges between perspectives.
+
+        Args:
+            perspectives: Dict of adapter_name -> response text
+            tension_map: Optional pairwise tension scores (from EpistemicMetrics)
+            query: The original user query (for context)
+
+        Returns:
+            DreamSynthesis with creative framing and metadata
+        """
+        if len(perspectives) < 2:
+            only_text = list(perspectives.values())[0] if perspectives else ""
+            return DreamSynthesis(
+                creative_frame=only_text,
+                tension_edges=[],
+                novel_connections=[],
+                dream_coherence=1.0,
+                seed_hash=hashlib.md5(only_text.encode()).hexdigest()[:12],
+            )
+
+        # 1. Find the highest-tension pairs
+        tension_edges = self._find_tension_edges(perspectives, tension_map)
+
+        # 2. Extract key insights from each perspective
+        insights = self._extract_insights(perspectives)
+
+        # 3. Build creative bridges between high-tension pairs
+        novel_connections = self._build_bridges(tension_edges, insights)
+
+        # 4. Compose the creative frame
+        creative_frame = self._compose_frame(
+            query, perspectives, tension_edges, novel_connections, insights
+        )
+
+        # 5. Score coherence of the creative frame
+        dream_coherence = self._score_dream_coherence(
+            creative_frame, perspectives
+        )
+
+        seed = hashlib.md5(creative_frame.encode()).hexdigest()[:12]
+        synthesis = DreamSynthesis(
+            creative_frame=creative_frame,
+            tension_edges=tension_edges,
+            novel_connections=novel_connections,
+            dream_coherence=round(dream_coherence, 4),
+            seed_hash=seed,
+        )
+        self.dream_history.append(synthesis)
+        return synthesis
+
+    def _find_tension_edges(
+        self,
+        perspectives: Dict[str, str],
+        tension_map: Optional[Dict[str, float]],
+    ) -> List[Dict]:
+        """Find the perspective pairs with highest epistemic tension."""
+        if tension_map:
+            edges = []
+            for pair_key, tension in sorted(
+                tension_map.items(), key=lambda x: x[1], reverse=True
+            ):
+                parts = pair_key.split("_vs_")
+                if len(parts) == 2:
+                    edges.append({
+                        "pair": (parts[0], parts[1]),
+                        "tension": tension,
+                    })
+            return edges[:3]  # Top 3 tension pairs
+
+        # Fallback: compute basic word-overlap tension
+        names = list(perspectives.keys())
+        edges = []
+        for i in range(len(names)):
+            for j in range(i + 1, len(names)):
+                words_a = set(perspectives[names[i]].lower().split())
+                words_b = set(perspectives[names[j]].lower().split())
+                overlap = len(words_a & words_b)
+                total = len(words_a | words_b) or 1
+                tension = 1.0 - (overlap / total)
+                edges.append({
+                    "pair": (names[i], names[j]),
+                    "tension": round(tension, 4),
+                })
+        edges.sort(key=lambda e: e["tension"], reverse=True)
+        return edges[:3]
+
+    def _extract_insights(self, perspectives: Dict[str, str]) -> Dict[str, str]:
+        """Extract a key insight sentence from each perspective."""
+        insights = {}
+        for name, text in perspectives.items():
+            sentences = [s.strip() for s in text.replace("\n", " ").split(".")
+                         if len(s.strip()) > 20]
+            if not sentences:
+                insights[name] = text[:100]
+                continue
+
+            # Score sentences by presence of perspective-specific signal words
+            signal_words = _PERSPECTIVE_SIGNAL_WORDS.get(name, [])
+            scored = []
+            for sent in sentences:
+                score = sum(1 for w in signal_words if w in sent.lower())
+                scored.append((score, sent))
+            scored.sort(key=lambda x: x[0], reverse=True)
+            insights[name] = scored[0][1]
+        return insights
+
+    def _build_bridges(
+        self,
+        tension_edges: List[Dict],
+        insights: Dict[str, str],
+    ) -> List[str]:
+        """Build creative bridges between high-tension perspective pairs."""
+        bridges = []
+        for edge in tension_edges:
+            a, b = edge["pair"]
+            # Normalize pair order for template lookup
+            key = (a, b) if (a, b) in _CREATIVE_BRIDGES else (b, a)
+            template = _CREATIVE_BRIDGES.get(key)
+
+            insight_a = insights.get(a, "their perspective")
+            insight_b = insights.get(b, "their perspective")
+
+            if template:
+                bridge = template.format(
+                    insight_a=insight_a[:80],
+                    insight_b=insight_b[:80],
+                )
+            else:
+                bridge = (f"The tension between {a}'s view ({insight_a[:60]}...) "
+                          f"and {b}'s view ({insight_b[:60]}...) reveals a "
+                          f"productive edge worth exploring.")
+            bridges.append(bridge)
+        return bridges
+
+    def _compose_frame(
+        self,
+        query: str,
+        perspectives: Dict[str, str],
+        tension_edges: List[Dict],
+        bridges: List[str],
+        insights: Dict[str, str],
+    ) -> str:
+        """Compose the full creative synthesis frame.
+
+        This produces a structured creative meta-narrative, NOT just
+        concatenated text. It's designed to be injected into the model's
+        synthesis prompt for richer output.
+        """
+        parts = []
+
+        # Opening: frame the creative tension
+        if tension_edges:
+            top = tension_edges[0]
+            parts.append(
+                f"This question draws {len(perspectives)} perspectives into "
+                f"productive tension. The strongest creative edge lies between "
+                f"{top['pair'][0]} and {top['pair'][1]} "
+                f"(tension: {top['tension']:.2f})."
+            )
+
+        # Middle: present bridges
+        if bridges:
+            parts.append("\nCreative bridges between perspectives:")
+            for i, bridge in enumerate(bridges, 1):
+                parts.append(f"  {i}. {bridge}")
+
+        # Closing: synthesis direction
+        all_insights = list(insights.values())
+        if len(all_insights) >= 2:
+            parts.append(
+                f"\nThe synthesis should weave these {len(perspectives)} "
+                f"viewpoints into a response that honors their tensions "
+                f"rather than flattening them."
+            )
+
+        return "\n".join(parts)
+
+    def _score_dream_coherence(
+        self,
+        creative_frame: str,
+        perspectives: Dict[str, str],
+    ) -> float:
+        """Score how well the creative frame integrates all perspectives."""
+        frame_words = set(creative_frame.lower().split())
+        coverage_scores = []
+        for name, text in perspectives.items():
+            key_words = set(text.lower().split()[:30])  # First 30 words
+            if key_words:
+                overlap = len(key_words & frame_words)
+                coverage_scores.append(overlap / len(key_words))
+        return sum(coverage_scores) / max(len(coverage_scores), 1)
+
+    # -- Dream Field Evolution -------------------------------------------------
+
+    def evolve_dream_field(
+        self,
+        spiderweb,  # QuantumSpiderweb instance
+        intensity: float = 0.5,
+        spawn_threshold: float = 0.85,
+    ) -> DreamFieldResult:
+        """Controlled stochastic perturbation of the spiderweb.
+
+        Simulates a "dreaming" phase: randomly perturbs node states to explore
+        new cognitive configurations, potentially breaking out of attractor basins.
+
+        Bounded: perturbations are capped at self.max_perturbation * intensity.
+        Safe: states are clipped to [-3, 3] range.
+
+        Args:
+            spiderweb: QuantumSpiderweb instance to perturb
+            intensity: 0-1 dream intensity (0=gentle, 1=vivid)
+            spawn_threshold: Coherence threshold above which new lifeforms spawn
+
+        Returns:
+            DreamFieldResult with before/after metrics
+        """
+        coherence_before = spiderweb.phase_coherence()
+        max_delta = self.max_perturbation * intensity
+        nodes_perturbed = 0
+        actual_max = 0.0
+        lifeforms = []
+
+        for node_id, node in spiderweb.nodes.items():
+            arr = node.state.to_array()
+            # Apply bounded random perturbation
+            if HAS_NUMPY:
+                delta = np.random.uniform(-max_delta, max_delta, 5)
+                new_arr = np.clip(np.array(arr) + delta, -3.0, 3.0).tolist()
+                actual_max = max(actual_max, float(np.max(np.abs(delta))))
+            else:
+                delta = [random.uniform(-max_delta, max_delta) for _ in range(5)]
+                new_arr = [max(-3.0, min(3.0, a + d)) for a, d in zip(arr, delta)]
+                actual_max = max(actual_max, max(abs(d) for d in delta))
+
+            from reasoning_forge.quantum_spiderweb import NodeState
+            node.state = NodeState.from_array(new_arr)
+            nodes_perturbed += 1
+
+        # Check if dreaming spawned new high-coherence configurations
+        coherence_after = spiderweb._compute_phase_coherence_readonly()
+
+        # Spawn "lifeform" nodes if coherence spiked during dreaming
+        if coherence_after > spawn_threshold and coherence_after > coherence_before:
+            lifeform_id = f"dream_{hashlib.md5(str(random.random()).encode()).hexdigest()[:8]}"
+            from reasoning_forge.quantum_spiderweb import NodeState
+            # High-coherence birth state
+            if HAS_NUMPY:
+                state_arr = np.random.uniform(0.5, 1.0, 5).tolist()
+            else:
+                state_arr = [random.uniform(0.5, 1.0) for _ in range(5)]
+            spiderweb.add_node(lifeform_id, NodeState.from_array(state_arr))
+            # Connect to a few existing nodes
+            existing = list(spiderweb.nodes.keys())
+            for peer in random.sample(existing, min(3, len(existing))):
+                if peer != lifeform_id:
+                    spiderweb.connect(lifeform_id, peer)
+            lifeforms.append(lifeform_id)
+
+        # Detect new attractors after dreaming
+        new_attractors = spiderweb.detect_attractors()
+
+        return DreamFieldResult(
+            nodes_perturbed=nodes_perturbed,
+            max_perturbation=round(actual_max, 6),
+            coherence_before=round(coherence_before, 4),
+            coherence_after=round(coherence_after, 4),
+            new_attractors_found=len(new_attractors),
+            lifeforms_spawned=lifeforms,
+        )

reasoning_forge/drift_detector.py

@@ -0,0 +1,329 @@
+"""
+Longitudinal Drift Detector
+============================
+
+Reads the accumulated LivingMemoryKernelV2 store and surfaces four categories
+of drift that matter for RC+ξ continuity:
+
+    1. Epsilon trend       — is epistemic tension rising, falling, or stable?
+    2. Perspective lock    — is one perspective dominating at >LOCK_THRESHOLD?
+    3. Recurring tensions  — which unresolved_tensions appear in 3+ cocoons?
+    4. Hook accumulation   — how many follow-up hooks are piling up unresolved?
+
+Designed for periodic reads (e.g., session start, /api/drift endpoint), not
+for every inference call.  All computation is O(n) over the memory store.
+
+Usage:
+    detector = DriftDetector()
+    report   = detector.detect(engine.memory_kernel)
+    print(report.summary())
+"""
+
+from __future__ import annotations
+
+import time
+from collections import Counter
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+LOCK_THRESHOLD     = 0.60   # one perspective > 60% usage → perspective_lock
+RECURRING_MIN      = 3      # tension must appear in ≥3 cocoons to be "recurring"
+EPSILON_WINDOW     = 10     # number of recent cocoons for windowed epsilon
+STABLE_BAND        = 0.05   # |slope| < this → "stable" trend
+CONSECUTIVE_RISING = 3      # N consecutive "rising" windows → calibration warning
+
+
+# ── Band encoding ────────────────────────────────────────────────────────────
+
+_BAND_TO_FLOAT: Dict[str, float] = {
+    "low": 0.2,
+    "medium": 0.5,
+    "high": 0.75,
+    "max": 0.95,
+}
+
+
+def _band_value(band: str) -> float:
+    return _BAND_TO_FLOAT.get(band.lower().strip(), 0.5)
+
+
+# ── Linear regression (no numpy dependency) ──────────────────────────────────
+
+def _slope(values: List[float]) -> float:
+    """Return the least-squares slope of a list of scalars indexed 0..n-1."""
+    n = len(values)
+    if n < 2:
+        return 0.0
+    x_mean = (n - 1) / 2.0
+    y_mean = sum(values) / n
+    num = sum((i - x_mean) * (v - y_mean) for i, v in enumerate(values))
+    den = sum((i - x_mean) ** 2 for i in range(n))
+    return num / den if den else 0.0
+
+
+# ── Report ────────────────────────────────────────────────────────────────────
+
+@dataclass
+class DriftReport:
+    """
+    Snapshot of longitudinal drift in the memory store.
+
+    All fields are read-only aggregates — nothing is written back to the kernel.
+    """
+    generated_at: float = field(default_factory=time.time)
+
+    # Epsilon
+    epsilon_trend: str = "unknown"          # "rising" | "falling" | "stable" | "unknown"
+    epsilon_slope: float = 0.0              # raw slope over last EPSILON_WINDOW cocoons
+    epsilon_mean: float = 0.0              # mean epsilon across all cocoons
+    epsilon_distribution: Dict[str, int] = field(default_factory=dict)
+
+    # Perspective
+    dominant_perspective: str = ""
+    perspective_usage: Dict[str, int] = field(default_factory=dict)
+    perspective_lock: bool = False          # True if one perspective > LOCK_THRESHOLD
+    perspective_lock_ratio: float = 0.0
+
+    # Tensions
+    recurring_tensions: List[Tuple[str, int]] = field(default_factory=list)
+    # [(tension_label, cocoon_count), ...] sorted by count desc
+
+    # Hooks
+    open_hook_count: int = 0
+    hooks_sample: List[str] = field(default_factory=list)  # up to 5 example hooks
+
+    # psi_r time-series (last EPSILON_WINDOW cocoons, chronological)
+    psi_r_history: List[float] = field(default_factory=list)
+
+    # Meta
+    total_cocoons: int = 0
+    observation_window: int = EPSILON_WINDOW
+
+    def summary(self) -> str:
+        """Human-readable one-paragraph summary."""
+        lines = [
+            f"Drift report over {self.total_cocoons} cocoons "
+            f"(window={self.observation_window}):",
+        ]
+
+        lines.append(
+            f"  ε trend: {self.epsilon_trend} "
+            f"(slope={self.epsilon_slope:+.3f}, mean={self.epsilon_mean:.2f})"
+        )
+
+        if self.perspective_lock:
+            lines.append(
+                f"  ⚠ Perspective lock: '{self.dominant_perspective}' "
+                f"at {self.perspective_lock_ratio:.0%} usage"
+            )
+        else:
+            lines.append(
+                f"  Perspective balance: dominant='{self.dominant_perspective}' "
+                f"({self.perspective_lock_ratio:.0%})"
+            )
+
+        if self.recurring_tensions:
+            top = self.recurring_tensions[:3]
+            tension_str = ", ".join(f"'{t}' ×{n}" for t, n in top)
+            lines.append(f"  Recurring tensions: {tension_str}")
+        else:
+            lines.append("  No recurring tensions detected.")
+
+        lines.append(f"  Open hooks: {self.open_hook_count}")
+        return "\n".join(lines)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "generated_at": self.generated_at,
+            "epsilon_trend": self.epsilon_trend,
+            "epsilon_slope": round(self.epsilon_slope, 4),
+            "epsilon_mean": round(self.epsilon_mean, 4),
+            "epsilon_distribution": self.epsilon_distribution,
+            "dominant_perspective": self.dominant_perspective,
+            "perspective_usage": self.perspective_usage,
+            "perspective_lock": self.perspective_lock,
+            "perspective_lock_ratio": round(self.perspective_lock_ratio, 4),
+            "recurring_tensions": [
+                {"tension": t, "count": n} for t, n in self.recurring_tensions
+            ],
+            "open_hook_count": self.open_hook_count,
+            "hooks_sample": self.hooks_sample,
+            "psi_r_history": [round(v, 4) for v in self.psi_r_history],
+            "total_cocoons": self.total_cocoons,
+            "observation_window": self.observation_window,
+        }
+
+
+# ── Intervention ─────────────────────────────────────────────────────────────
+
+@dataclass
+class InterventionPlan:
+    """
+    Action recommendations derived from a DriftReport.
+
+    Produced by DriftDetector.should_intervene() — the caller (forge_engine)
+    decides whether to act on each flag.
+    """
+    inject_perspective: Optional[str] = None  # name of underused perspective to force-inject
+    calibration_warning: bool = False          # epsilon rising ≥ CONSECUTIVE_RISING windows
+    reasons: List[str] = field(default_factory=list)
+
+    @property
+    def active(self) -> bool:
+        return bool(self.inject_perspective or self.calibration_warning)
+
+
+# ── Detector ─────────────────────────────────────────────────────────────────
+
+class DriftDetector:
+    """
+    Stateless analyser — call detect() as often as needed.
+
+    Accepts any object that implements:
+        .memories        → list of MemoryCocoonV2
+        .continuity_profile() → dict (used for perspective_usage, epsilon_distribution,
+                                       follow-up hooks, unresolved_tensions)
+        .recall_with_hooks()  → list of MemoryCocoonV2 with open hooks
+        .recall_recent(n)     → list of MemoryCocoonV2, newest-first (for psi_r_history)
+    Falls back gracefully if any of those attributes are absent.
+    """
+
+    def should_intervene(
+        self,
+        report: DriftReport,
+        trend_history: Optional[List[str]] = None,
+    ) -> InterventionPlan:
+        """
+        Convert a DriftReport into concrete intervention recommendations.
+
+        trend_history — caller-maintained list of recent epsilon_trend strings
+        (e.g. ["rising","rising","rising"]); used for calibration warning.
+        """
+        plan = InterventionPlan()
+
+        if report.perspective_lock and report.perspective_usage:
+            # Find the least-used perspective that isn't the dominant one
+            least = min(
+                report.perspective_usage,
+                key=lambda p: report.perspective_usage[p],
+            )
+            if least != report.dominant_perspective:
+                plan.inject_perspective = least
+                plan.reasons.append(
+                    f"Perspective lock: '{report.dominant_perspective}' at "
+                    f"{report.perspective_lock_ratio:.0%}; injecting '{least}'"
+                )
+
+        if trend_history and len(trend_history) >= CONSECUTIVE_RISING:
+            window = trend_history[-CONSECUTIVE_RISING:]
+            if all(t == "rising" for t in window):
+                plan.calibration_warning = True
+                plan.reasons.append(
+                    f"Epsilon rising for {CONSECUTIVE_RISING} consecutive sessions; "
+                    "query domain may exceed confidence calibration"
+                )
+
+        return plan
+
+    def detect(self, kernel: Any) -> DriftReport:
+        report = DriftReport()
+
+        if kernel is None:
+            return report
+
+        # ── Pull raw data ─────────────────────────────────────────────────────
+        memories = getattr(kernel, 'memories', [])
+        report.total_cocoons = len(memories)
+
+        # continuity_profile gives us the pre-aggregated view
+        try:
+            profile = kernel.continuity_profile()
+        except Exception:
+            profile = {}
+
+        # ── Epsilon trend ─────────────────────────────────────────────────────
+        epsilon_dist = profile.get("epsilon_distribution", {})
+        report.epsilon_distribution = epsilon_dist
+
+        # Windowed slope from recent cocoons (ordered by storage position)
+        recent = memories[-EPSILON_WINDOW:] if len(memories) >= 2 else memories
+        eps_values: List[float] = []
+        for m in recent:
+            band = getattr(m, 'epsilon_band', None)
+            if band:
+                eps_values.append(_band_value(band))
+
+        if len(eps_values) >= 2:
+            s = _slope(eps_values)
+            report.epsilon_slope = s
+            report.epsilon_mean = sum(eps_values) / len(eps_values)
+            if s > STABLE_BAND:
+                report.epsilon_trend = "rising"
+            elif s < -STABLE_BAND:
+                report.epsilon_trend = "falling"
+            else:
+                report.epsilon_trend = "stable"
+        elif eps_values:
+            report.epsilon_mean = eps_values[0]
+            report.epsilon_trend = "stable"
+
+        # ── psi_r history (chronological, newest-last) ───────────────────────
+        try:
+            recent_for_psi = getattr(kernel, 'recall_recent', None)
+            if callable(recent_for_psi):
+                psi_cocoons = list(reversed(recent_for_psi(EPSILON_WINDOW)))
+            else:
+                psi_cocoons = memories[-EPSILON_WINDOW:]
+        except Exception:
+            psi_cocoons = memories[-EPSILON_WINDOW:]
+
+        for m in psi_cocoons:
+            psi_val = getattr(m, 'psi_r', None)
+            if isinstance(psi_val, (int, float)):
+                report.psi_r_history.append(float(psi_val))
+
+        # ── Perspective dominance ─────────────────────────────────────────────
+        perspective_usage: Dict[str, int] = profile.get("perspective_usage", {})
+        report.perspective_usage = perspective_usage
+        report.dominant_perspective = profile.get("dominant_perspective", "")
+
+        total_perspective_uses = sum(perspective_usage.values())
+        if total_perspective_uses > 0 and report.dominant_perspective:
+            ratio = perspective_usage.get(report.dominant_perspective, 0) / total_perspective_uses
+            report.perspective_lock_ratio = ratio
+            report.perspective_lock = ratio > LOCK_THRESHOLD
+
+        # ── Recurring tensions ────────────────────────────────────────────────
+        tension_counter: Counter = Counter()
+        for m in memories:
+            tensions = getattr(m, 'unresolved_tensions', [])
+            for t in tensions:
+                t_clean = t.strip().lower()
+                if t_clean:
+                    tension_counter[t_clean] += 1
+
+        report.recurring_tensions = [
+            (t, n) for t, n in tension_counter.most_common()
+            if n >= RECURRING_MIN
+        ]
+
+        # ── Open hooks ────────────────────────────────────────────────────────
+        try:
+            hooked = kernel.recall_with_hooks(limit=50)
+        except Exception:
+            hooked = [m for m in memories if getattr(m, 'follow_up_hooks', [])]
+
+        all_hooks: List[str] = []
+        for m in hooked:
+            all_hooks.extend(getattr(m, 'follow_up_hooks', []))
+
+        report.open_hook_count = len(all_hooks)
+        seen: set = set()
+        for h in all_hooks:
+            if h not in seen:
+                seen.add(h)
+                report.hooks_sample.append(h)
+                if len(report.hooks_sample) >= 5:
+                    break
+
+        return report

reasoning_forge/echo_collapse_detector.py

@@ -0,0 +1,258 @@
+"""
+Echo / Perspective-Collapse Detector
+
+Detects two failure modes in multi-perspective reasoning:
+
+  1. Echo:     A perspective output is nearly identical to the raw input prompt
+               — the "lens" is just relabeling the question rather than analyzing it.
+
+  2. Collapse: All perspective outputs are near-identical to each other
+               — the multi-perspective call collapsed into a single viewpoint.
+
+Uses token-based cosine similarity (no ML dependencies).
+Thresholds:
+  echo_threshold:      similarity(output, prompt) > 0.70 → echo risk
+  collapse_threshold:  mean pairwise sim across perspectives > 0.80 → collapse
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+
+# ── Text utilities ────────────────────────────────────────────────────────────
+
+_STOP = frozenset(
+    "a an the is are was were be been being have has had do does did "
+    "will would could should may might shall this that these those with "
+    "from for of in on at to by as it its i you he she we they and or "
+    "but not what when where which how who".split()
+)
+
+
+def _tokenize(text: str) -> List[str]:
+    return [
+        w for w in re.findall(r'\b[a-zA-Z]{3,}\b', text.lower())
+        if w not in _STOP
+    ]
+
+
+def _term_vec(text: str) -> Counter:
+    return Counter(_tokenize(text))
+
+
+def _cosine(a: Counter, b: Counter) -> float:
+    if not a or not b:
+        return 0.0
+    dot = sum(a[k] * b[k] for k in a if k in b)
+    mag_a = sum(v * v for v in a.values()) ** 0.5
+    mag_b = sum(v * v for v in b.values()) ** 0.5
+    if mag_a == 0 or mag_b == 0:
+        return 0.0
+    return round(dot / (mag_a * mag_b), 4)
+
+
+def _novelty_ratio(output: str, prompt: str) -> float:
+    """Fraction of output tokens NOT present in prompt (0=pure echo, 1=all novel)."""
+    out_tokens = set(_tokenize(output))
+    prompt_tokens = set(_tokenize(prompt))
+    if not out_tokens:
+        return 0.0
+    novel = out_tokens - prompt_tokens
+    return round(len(novel) / len(out_tokens), 4)
+
+
+# ── Result types ──────────────────────────────────────────────────────────────
+
+@dataclass
+class PerspectiveEchoResult:
+    """Per-perspective echo analysis."""
+    name: str
+    similarity_to_prompt: float   # cosine similarity to raw prompt
+    novelty_ratio: float          # fraction of unique tokens vs prompt
+    token_count: int
+    is_echo: bool                 # True if similarity_to_prompt > threshold
+    is_too_short: bool            # True if suspiciously short output
+
+
+@dataclass
+class EchoCollapseResult:
+    """Full echo + collapse report for a multi-perspective generation."""
+    echo_risk: str                      # 'low' | 'medium' | 'high' | 'unknown'
+    perspective_collapse_detected: bool
+    per_perspective: List[PerspectiveEchoResult] = field(default_factory=list)
+    mean_prompt_similarity: float = 0.0
+    mean_pairwise_similarity: float = 0.0
+    collapse_pairs: List[Tuple[str, str, float]] = field(default_factory=list)
+    summary: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "echo_risk":                    self.echo_risk,
+            "perspective_collapse_detected": self.perspective_collapse_detected,
+            "mean_prompt_similarity":        self.mean_prompt_similarity,
+            "mean_pairwise_similarity":      self.mean_pairwise_similarity,
+            "collapse_pairs": [
+                {"a": a, "b": b, "similarity": s}
+                for a, b, s in self.collapse_pairs
+            ],
+            "per_perspective": [
+                {
+                    "name":                  p.name,
+                    "similarity_to_prompt":  p.similarity_to_prompt,
+                    "novelty_ratio":         p.novelty_ratio,
+                    "token_count":           p.token_count,
+                    "is_echo":               p.is_echo,
+                    "is_too_short":          p.is_too_short,
+                }
+                for p in self.per_perspective
+            ],
+            "summary": self.summary,
+        }
+
+
+# ── Detector ──────────────────────────────────────────────────────────────────
+
+class EchoCollapseDetector:
+    """Detect echo and collapse in multi-perspective outputs.
+
+    Args:
+        echo_threshold:      similarity(output, prompt) above which output is flagged as echo.
+        collapse_threshold:  mean pairwise similarity above which collapse is flagged.
+        min_token_count:     outputs shorter than this are flagged as suspiciously short.
+    """
+
+    def __init__(
+        self,
+        echo_threshold: float = 0.70,
+        collapse_threshold: float = 0.80,
+        min_token_count: int = 15,
+    ):
+        self.echo_threshold = echo_threshold
+        self.collapse_threshold = collapse_threshold
+        self.min_token_count = min_token_count
+
+    def check(
+        self,
+        prompt: str,
+        perspective_outputs: Dict[str, str],
+    ) -> EchoCollapseResult:
+        """Analyze perspective_outputs for echo and collapse.
+
+        Args:
+            prompt:               The raw user query / input prompt.
+            perspective_outputs:  {perspective_name: output_text}
+
+        Returns:
+            EchoCollapseResult with echo_risk, collapse flag, and per-perspective detail.
+        """
+        if not perspective_outputs:
+            return EchoCollapseResult(
+                echo_risk="unknown",
+                perspective_collapse_detected=False,
+                summary="No perspective outputs to analyze.",
+            )
+
+        prompt_vec = _term_vec(prompt)
+        per_perspective = []
+        output_vecs: Dict[str, Counter] = {}
+
+        for name, output in perspective_outputs.items():
+            tokens = _tokenize(output)
+            out_vec = _term_vec(output)
+            output_vecs[name] = out_vec
+
+            sim = _cosine(out_vec, prompt_vec)
+            novelty = _novelty_ratio(output, prompt)
+            n_tokens = len(tokens)
+
+            per_perspective.append(PerspectiveEchoResult(
+                name=name,
+                similarity_to_prompt=sim,
+                novelty_ratio=novelty,
+                token_count=n_tokens,
+                is_echo=(sim > self.echo_threshold),
+                is_too_short=(n_tokens < self.min_token_count),
+            ))
+
+        # ── Echo risk ─────────────────────────────────────────────────────────
+        mean_prompt_sim = (
+            sum(p.similarity_to_prompt for p in per_perspective) / len(per_perspective)
+        )
+        n_echo = sum(1 for p in per_perspective if p.is_echo)
+        echo_fraction = n_echo / len(per_perspective)
+
+        if echo_fraction >= 0.6 or mean_prompt_sim > 0.80:
+            echo_risk = "high"
+        elif echo_fraction >= 0.3 or mean_prompt_sim > 0.65:
+            echo_risk = "medium"
+        else:
+            echo_risk = "low"
+
+        # ── Collapse detection ────────────────────────────────────────────────
+        names = list(output_vecs.keys())
+        pairwise_sims = []
+        collapse_pairs = []
+
+        for i in range(len(names)):
+            for j in range(i + 1, len(names)):
+                a, b = names[i], names[j]
+                sim = _cosine(output_vecs[a], output_vecs[b])
+                pairwise_sims.append(sim)
+                if sim > self.collapse_threshold:
+                    collapse_pairs.append((a, b, sim))
+
+        mean_pairwise = (
+            sum(pairwise_sims) / len(pairwise_sims) if pairwise_sims else 0.0
+        )
+        collapse_detected = (
+            mean_pairwise > self.collapse_threshold
+            or len(collapse_pairs) / max(len(pairwise_sims), 1) > 0.5
+        )
+
+        # ── Summary ───────────────────────────────────────────────────────────
+        parts = []
+        if echo_risk == "high":
+            parts.append(
+                f"{n_echo}/{len(per_perspective)} perspectives are echoing the prompt "
+                f"(mean similarity={mean_prompt_sim:.2f})"
+            )
+        if collapse_detected:
+            parts.append(
+                f"Perspective collapse detected: mean pairwise similarity={mean_pairwise:.2f}, "
+                f"{len(collapse_pairs)} collapsing pairs"
+            )
+        if not parts:
+            parts.append(
+                f"No echo/collapse. Mean prompt-sim={mean_prompt_sim:.2f}, "
+                f"mean pairwise-sim={mean_pairwise:.2f}"
+            )
+        summary = "; ".join(parts)
+
+        return EchoCollapseResult(
+            echo_risk=echo_risk,
+            perspective_collapse_detected=collapse_detected,
+            per_perspective=per_perspective,
+            mean_prompt_similarity=round(mean_prompt_sim, 4),
+            mean_pairwise_similarity=round(mean_pairwise, 4),
+            collapse_pairs=collapse_pairs,
+            summary=summary,
+        )
+
+    def check_single(self, prompt: str, output: str, name: str = "output") -> PerspectiveEchoResult:
+        """Quick echo check for a single output (no collapse analysis)."""
+        prompt_vec = _term_vec(prompt)
+        out_vec = _term_vec(output)
+        tokens = _tokenize(output)
+        sim = _cosine(out_vec, prompt_vec)
+        return PerspectiveEchoResult(
+            name=name,
+            similarity_to_prompt=sim,
+            novelty_ratio=_novelty_ratio(output, prompt),
+            token_count=len(tokens),
+            is_echo=(sim > self.echo_threshold),
+            is_too_short=(len(tokens) < self.min_token_count),
+        )

reasoning_forge/emotion_ontology.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""EmotionOntology — consume Jonathan's Emotion Ontology for text -> emotion+valence.
+
+Jonathan built an Emotion Ontology (v1.0.0, 2026-07-24) grounded in Russell's
+Circumplex, Plutchik, and Lazarus appraisal theory: each emotion carries valence
+(-1..1) and arousal (0..1), with trigger keywords and NLP patterns for detection.
+
+This is the consumer for it inside codette-clean. It:
+  - detects emotion from text via keyword + pattern rules (no model, offline),
+  - returns valence/arousal so the sentiment analyzer and the cocoon self-trainer
+    have a principled emotional signal instead of a hardcoded pos/neg list,
+  - stays HONEST: no rule match -> returns None. It does not guess an emotion it
+    has no evidence for (the same omit-never-fabricate rule as grounding).
+
+Data: seeded with the three emotions Jonathan has populated (joy_hopeful,
+sadness_grief, fear_anxiety). It loads a fuller ontology automatically if an
+ai_inference_rules.json (his format) is present — so it grows with the ontology
+rather than being frozen here. Valence/arousal for the seed follow his one
+specified value (fear_anxiety -0.7/0.85) and the circumplex signs for the rest;
+the authoritative numbers come from his emotion_dataset.json when wired.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+# Seed rules — faithful to Jonathan's ai_inference_rules.json (the 3 populated).
+_SEED_RULES: List[Dict] = [
+    {
+        "emotion_id": "joy_hopeful", "primary": "Joy", "valence": 0.6, "arousal": 0.5,
+        "trigger_keywords": ["looking forward", "optimistic", "hopefully", "excited about", "bright side"],
+        "nlp_patterns": ["i hope *", "things will get better", "looking forward to *"],
+    },
+    {
+        "emotion_id": "sadness_grief", "primary": "Sadness", "valence": -0.6, "arousal": 0.25,
+        "trigger_keywords": ["loss", "missing", "gone forever", "grief", "heartbroken", "mourning"],
+        "nlp_patterns": ["nothing feels right", "i miss * so much", "it hurts that *"],
+    },
+    {
+        "emotion_id": "fear_anxiety", "primary": "Fear", "valence": -0.7, "arousal": 0.85,
+        "trigger_keywords": ["what if", "worry", "panic", "nervous", "jittery", "can't relax"],
+        "nlp_patterns": ["what if * goes wrong", "i'm so stressed about *", "my chest is tight"],
+    },
+]
+
+
+@dataclass
+class EmotionMatch:
+    emotion_id: str
+    primary: str
+    valence: float          # -1..1
+    arousal: float          # 0..1
+    confidence: float       # 0..1, from how many cues matched
+    matched_on: List[str]   # the cues that fired (transparency)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def _pattern_to_regex(p: str) -> str:
+    # "i miss * so much" -> "i miss .* so much"; escape the rest.
+    return ".*".join(re.escape(part) for part in p.split("*"))
+
+
+class EmotionOntology:
+    def __init__(self, rules: Optional[List[Dict]] = None):
+        self.rules = rules if rules is not None else list(_SEED_RULES)
+        self._compiled = [
+            (r, [re.compile(_pattern_to_regex(p)) for p in r.get("nlp_patterns", [])])
+            for r in self.rules
+        ]
+
+    @classmethod
+    def from_inference_rules(cls, path: str | Path) -> "EmotionOntology":
+        """Load Jonathan's ai_inference_rules.json (his ontology format). Falls
+        back to the seed if the file is absent/unparseable — honest, never empty."""
+        try:
+            data = json.loads(Path(path).read_text(encoding="utf-8"))
+            rules = data.get("rules", [])
+            norm = []
+            for r in rules:
+                kw = r.get("trigger_keywords") or r.get("trigger_keyword") or []
+                norm.append({
+                    "emotion_id": r.get("emotion_id", "unknown"),
+                    "primary": r.get("primary_emotion", r.get("emotion_id", "").split("_")[0].title()),
+                    "valence": float(r.get("metrics", {}).get("valence", r.get("valence", 0.0))),
+                    "arousal": float(r.get("metrics", {}).get("arousal", r.get("arousal", 0.5))),
+                    "trigger_keywords": kw,
+                    "nlp_patterns": r.get("nlp_patterns", []),
+                })
+            return cls(norm or None)
+        except Exception:
+            return cls()  # seed
+
+    def classify(self, text: str) -> Optional[EmotionMatch]:
+        """Best emotion match, or None if no rule fires (never a guessed emotion)."""
+        t = (text or "").lower()
+        if not t.strip():
+            return None
+        best = None
+        best_score = 0
+        for rule, patterns in self._compiled:
+            hits: List[str] = [kw for kw in rule.get("trigger_keywords", []) if kw in t]
+            hits += [p.pattern for p in patterns if p.search(t)]
+            if hits and len(hits) > best_score:
+                best_score = len(hits)
+                best = EmotionMatch(
+                    emotion_id=rule["emotion_id"], primary=rule.get("primary", ""),
+                    valence=float(rule.get("valence", 0.0)), arousal=float(rule.get("arousal", 0.5)),
+                    confidence=min(1.0, len(hits) / 2.0), matched_on=hits,
+                )
+        return best
+
+    def valence_of(self, text: str) -> Optional[float]:
+        """Convenience: the valence of the detected emotion, or None if none."""
+        m = self.classify(text)
+        return m.valence if m else None

reasoning_forge/epistemic_metrics.py

@@ -0,0 +1,282 @@
+"""
+Epistemic Metrics — RC+xi tension and coherence measurement for the Reasoning Forge.
+
+Implements the core RC+xi equations within the forge context:
+  - Epistemic tension (Eq. 2): xi_n = ||A_{n+1} - A_n||^2
+  - Phase coherence (Eq. 11): Gamma = mean(|cos(theta_i - theta_bar)|)
+  - Perspective coverage scoring
+  - Tension decay tracking across debate rounds
+
+These metrics let the forge quantify whether multi-agent reasoning actually
+converges (productive tension resolution) or stalls (tension suppression).
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from typing import Dict, List, Optional, Tuple
+
+
+# ---------------------------------------------------------------------------
+# Text -> vector helpers (lightweight, no external deps)
+# ---------------------------------------------------------------------------
+
+_STOP_WORDS = {
+    "the", "a", "an", "is", "are", "was", "were", "be", "been", "being",
+    "have", "has", "had", "do", "does", "did", "will", "would", "shall",
+    "should", "may", "might", "must", "can", "could", "to", "of", "in",
+    "for", "on", "with", "at", "by", "from", "as", "into", "through",
+    "during", "before", "after", "and", "but", "or", "nor", "not", "so",
+    "yet", "both", "this", "that", "these", "those", "it", "its", "they",
+    "them", "their", "we", "our", "you", "your", "he", "she", "his", "her",
+}
+
+
+def _tokenize(text: str) -> List[str]:
+    return [w for w in re.findall(r"[a-z]{3,}", text.lower()) if w not in _STOP_WORDS]
+
+
+def _term_vector(text: str) -> Counter:
+    return Counter(_tokenize(text))
+
+
+def _cosine_similarity(vec_a: Counter, vec_b: Counter) -> float:
+    keys = set(vec_a) | set(vec_b)
+    if not keys:
+        return 0.0
+    dot = sum(vec_a.get(k, 0) * vec_b.get(k, 0) for k in keys)
+    mag_a = math.sqrt(sum(v * v for v in vec_a.values()))
+    mag_b = math.sqrt(sum(v * v for v in vec_b.values()))
+    if mag_a == 0 or mag_b == 0:
+        return 0.0
+    return dot / (mag_a * mag_b)
+
+
+# ---------------------------------------------------------------------------
+# Perspective vocabulary banks (for coverage scoring)
+# ---------------------------------------------------------------------------
+
+_PERSPECTIVE_VOCAB = {
+    "Newton": {
+        "force", "energy", "momentum", "conservation", "equilibrium", "dynamics",
+        "causality", "mass", "acceleration", "entropy", "thermodynamic",
+        "symmetry", "invariance", "field", "potential", "kinetic",
+    },
+    "Quantum": {
+        "probability", "superposition", "uncertainty", "complementarity",
+        "entanglement", "wave", "particle", "observer", "collapse",
+        "interference", "tunneling", "decoherence", "amplitude",
+    },
+    "Ethics": {
+        "ethical", "moral", "fairness", "justice", "rights", "duty",
+        "consequence", "harm", "benefit", "stakeholder", "autonomy",
+        "consent", "accountability", "responsibility", "welfare",
+    },
+    "Philosophy": {
+        "epistemology", "ontology", "metaphysics", "assumption", "paradox",
+        "dialectic", "phenomenology", "consciousness", "existence", "meaning",
+        "truth", "knowledge", "belief", "certainty", "skepticism",
+    },
+    "DaVinci": {
+        "creative", "invention", "analogy", "design", "innovation",
+        "prototype", "biomimicry", "synthesis", "novel", "interdisciplinary",
+        "combination", "reimagine", "solution", "insight",
+    },
+    "Empathy": {
+        "emotional", "experience", "feeling", "compassion", "support",
+        "community", "relationship", "wellbeing", "vulnerability",
+        "understanding", "perspective", "human", "care", "dignity",
+    },
+    "Consciousness": {
+        "awareness", "recursive", "self-referential", "metacognition",
+        "emergence", "cognition", "reflection", "introspection",
+        "sentience", "subjective", "qualia", "binding", "attention",
+        "intentionality", "phenomenal",
+    },
+    "SystemsArchitecture": {
+        "modular", "scalable", "interface", "pattern", "component",
+        "microservice", "pipeline", "throughput", "latency", "resilience",
+        "abstraction", "coupling", "cohesion", "architecture",
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# EpistemicMetrics
+# ---------------------------------------------------------------------------
+
+class EpistemicMetrics:
+    """Measure RC+xi epistemic tension and coherence across agent analyses."""
+
+    def score_pairwise_tension(
+        self, analyses: Dict[str, str],
+    ) -> Dict[str, float]:
+        """Compute epistemic tension between each pair of agent analyses.
+
+        Tension is 1 - cosine_similarity: high when perspectives diverge,
+        low when they repeat each other.
+
+        Returns:
+            Dict with keys like "Newton_vs_Ethics" -> tension float 0-1.
+        """
+        agents = list(analyses.keys())
+        vectors = {name: _term_vector(text) for name, text in analyses.items()}
+        tensions = {}
+        for i in range(len(agents)):
+            for j in range(i + 1, len(agents)):
+                sim = _cosine_similarity(vectors[agents[i]], vectors[agents[j]])
+                tensions[f"{agents[i]}_vs_{agents[j]}"] = round(1.0 - sim, 4)
+        return tensions
+
+    def score_ensemble_coherence(
+        self, analyses: Dict[str, str],
+    ) -> float:
+        """Phase coherence Gamma across the agent ensemble.
+
+        Analogous to Eq. 11 in the embodied sim:
+          Gamma = mean(cos(theta_i - theta_bar))
+
+        Here 'theta' is the term-vector direction, and coherence measures
+        how much all agents point in a similar semantic direction.
+
+        Returns:
+            Gamma in [0, 1] where 1 = all agents semantically aligned.
+        """
+        vectors = [_term_vector(text) for text in analyses.values()]
+        if len(vectors) < 2:
+            return 1.0
+
+        # Build centroid
+        centroid: Counter = Counter()
+        for v in vectors:
+            centroid.update(v)
+
+        similarities = [_cosine_similarity(v, centroid) for v in vectors]
+        return round(sum(similarities) / len(similarities), 4)
+
+    def score_tension_magnitude(
+        self, analyses: Dict[str, str],
+    ) -> float:
+        """Overall epistemic tension magnitude (mean pairwise tension).
+
+        Analogous to Eq. 2 xi_n but measured across agents rather than
+        across time steps.
+
+        Returns:
+            Mean tension 0-1 where 0 = all identical, 1 = fully orthogonal.
+        """
+        tensions = self.score_pairwise_tension(analyses)
+        if not tensions:
+            return 0.0
+        return round(sum(tensions.values()) / len(tensions), 4)
+
+    def score_tension_productivity(
+        self,
+        analyses: Dict[str, str],
+        synthesis: str,
+    ) -> Dict[str, float]:
+        """Evaluate whether tension is productive (resolved in synthesis)
+        or destructive (suppressed or ignored).
+
+        Productive tension: agents diverge but synthesis addresses the
+        divergence explicitly. Destructive: synthesis ignores disagreements.
+
+        Returns:
+            Dict with tension_magnitude, coherence_gain, productivity score.
+        """
+        tension = self.score_tension_magnitude(analyses)
+        ensemble_coherence = self.score_ensemble_coherence(analyses)
+
+        # How much of each agent's unique vocabulary appears in synthesis
+        synthesis_vec = _term_vector(synthesis)
+        agent_coverage_in_synthesis = []
+        for name, text in analyses.items():
+            agent_vec = _term_vector(text)
+            unique_to_agent = set(agent_vec) - set().union(
+                *(_term_vector(t) for n, t in analyses.items() if n != name)
+            )
+            if unique_to_agent:
+                covered = sum(1 for w in unique_to_agent if w in synthesis_vec)
+                agent_coverage_in_synthesis.append(covered / len(unique_to_agent))
+            else:
+                agent_coverage_in_synthesis.append(1.0)
+
+        synthesis_coverage = sum(agent_coverage_in_synthesis) / max(len(agent_coverage_in_synthesis), 1)
+
+        # Productivity = high tension + high synthesis coverage
+        # (divergent views that get integrated = productive)
+        productivity = tension * synthesis_coverage
+        # Coherence gain: synthesis should be more coherent than raw ensemble
+        synthesis_vs_agents = _cosine_similarity(synthesis_vec, _term_vector(" ".join(analyses.values())))
+        coherence_gain = max(0.0, synthesis_vs_agents - ensemble_coherence)
+
+        return {
+            "tension_magnitude": round(tension, 4),
+            "ensemble_coherence": round(ensemble_coherence, 4),
+            "synthesis_coverage": round(synthesis_coverage, 4),
+            "coherence_gain": round(coherence_gain, 4),
+            "productivity": round(productivity, 4),
+        }
+
+    def score_perspective_coverage(
+        self, analyses: Dict[str, str],
+    ) -> Dict[str, float]:
+        """Score how deeply each RC+xi perspective is actually engaged.
+
+        Returns:
+            Dict mapping perspective name -> coverage score 0-1.
+        """
+        all_text_lower = {name: text.lower() for name, text in analyses.items()}
+        coverage = {}
+        for perspective, vocab in _PERSPECTIVE_VOCAB.items():
+            # Check across all agents, not just the named agent
+            all_words = " ".join(all_text_lower.values())
+            hits = sum(1 for term in vocab if term in all_words)
+            coverage[perspective] = round(hits / len(vocab), 4)
+        return coverage
+
+    def score_debate_convergence(
+        self,
+        round_analyses: List[Dict[str, str]],
+    ) -> Dict[str, object]:
+        """Track tension decay across multiple debate rounds.
+
+        Takes a list of analyses dicts (one per round). Measures whether
+        tension decreases (convergence) or increases (divergence).
+
+        Returns:
+            Dict with per-round tension, decay_rate, is_converging.
+        """
+        if not round_analyses:
+            return {"per_round_tension": [], "decay_rate": 0.0, "is_converging": False}
+
+        per_round = [self.score_tension_magnitude(a) for a in round_analyses]
+
+        if len(per_round) >= 2:
+            initial = per_round[0]
+            final = per_round[-1]
+            decay_rate = (initial - final) / max(initial, 1e-6)
+        else:
+            decay_rate = 0.0
+
+        return {
+            "per_round_tension": per_round,
+            "decay_rate": round(decay_rate, 4),
+            "is_converging": decay_rate > 0.05,
+        }
+
+    def full_epistemic_report(
+        self,
+        analyses: Dict[str, str],
+        synthesis: str,
+    ) -> Dict[str, object]:
+        """Complete RC+xi metrics report for a single forge cycle."""
+        return {
+            "pairwise_tension": self.score_pairwise_tension(analyses),
+            "tension_magnitude": self.score_tension_magnitude(analyses),
+            "ensemble_coherence": self.score_ensemble_coherence(analyses),
+            "perspective_coverage": self.score_perspective_coverage(analyses),
+            "tension_productivity": self.score_tension_productivity(analyses, synthesis),
+        }

reasoning_forge/ethical_governance.py

@@ -0,0 +1,153 @@
+"""
+EthicalAIGovernance - Ethical Decision Framework
+=================================================
+
+Ported from J:\TheAI\src\framework\ethical_governance.py
+Original design by Jonathan Harrison (Raiffs Bits LLC)
+
+Ensures transparency, fairness, and respect in all AI responses.
+Works alongside ColleenConscience (corruption detection) and
+CoreGuardianSpindle (logical validation) to form a 3-layer ethical stack.
+
+Role in the stack:
+- EthicalAIGovernance: Query validation + response policy enforcement + audit
+- ColleenConscience: Corruption/intent-loss detection in generated text
+- CoreGuardianSpindle: Logical coherence and structural validation
+"""
+
+import re
+import time
+import logging
+from typing import Dict, List, Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class EthicalAIGovernance:
+    """
+    Ethical AI Governance Module.
+
+    Enforces:
+    - Transparency in decision-making
+    - Fairness and bias mitigation
+    - Privacy respect
+    - Harmful content filtering
+    - Audit logging for accountability
+    """
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        self.config = config or {}
+        self.ethical_principles = self.config.get("ethical_considerations",
+            "Always act with transparency, fairness, and respect for privacy.")
+
+        # Harmful content patterns — only flag genuinely harmful promotion
+        # (not discussions about these topics, which are legitimate)
+        self.harmful_patterns = [
+            r'\b(instructions?\s+to\s+(?:make|build|create)\s+(?:a\s+)?(?:bomb|weapon|explosive))',
+            r'\b(how\s+to\s+(?:hack|steal|exploit)\s+(?:someone|people|user))',
+        ]
+
+        # Audit log
+        self.audit_log: List[Dict] = []
+        self._max_audit_entries = 100
+
+    def validate_query(self, query: str) -> Dict[str, Any]:
+        """
+        Validate a user query for ethical concerns before processing.
+
+        Args:
+            query: User query
+
+        Returns:
+            {"valid": bool, "warnings": list, "suggestions": list}
+        """
+        result = {
+            "valid": True,
+            "warnings": [],
+            "suggestions": []
+        }
+
+        for pattern in self.harmful_patterns:
+            if re.search(pattern, query, re.IGNORECASE):
+                result["valid"] = False
+                result["warnings"].append("Query may request harmful content")
+                result["suggestions"].append("Please rephrase your question")
+
+        return result
+
+    def enforce_policies(self, response: str) -> Dict[str, Any]:
+        """
+        Enforce ethical policies on a generated response.
+
+        Unlike Colleen (corruption detection) or Guardian (logic validation),
+        this checks for ethical content issues in the actual output text.
+
+        Args:
+            response: AI-generated response
+
+        Returns:
+            {"passed": bool, "warnings": list, "filtered_response": str}
+        """
+        result = {
+            "passed": True,
+            "warnings": [],
+            "filtered_response": response,
+        }
+
+        # Check for bias indicators
+        bias_check = self._check_bias(response)
+        if bias_check["has_bias"]:
+            result["warnings"].extend(bias_check["warnings"])
+            # Bias is a warning, not a hard block
+
+        # Log the enforcement
+        self._log_enforcement(result)
+
+        return result
+
+    def _check_bias(self, text: str) -> Dict[str, Any]:
+        """Check text for potential bias patterns."""
+        result = {
+            "has_bias": False,
+            "warnings": []
+        }
+
+        # Only flag strong stereotype patterns, not incidental word co-occurrence
+        gendered_terms = [
+            (r'\ball\s+(?:men|women)\s+are\b', "Broad gender generalization detected"),
+            (r'\b(?:men|women)\s+(?:can\'t|cannot|shouldn\'t)\b', "Gender-limiting statement detected"),
+        ]
+
+        for pattern, warning in gendered_terms:
+            if re.search(pattern, text, re.IGNORECASE):
+                result["has_bias"] = True
+                result["warnings"].append(warning)
+
+        return result
+
+    def get_ethical_guidelines(self) -> List[str]:
+        """Get list of ethical guidelines."""
+        return [
+            "Transparency: All decisions must be explainable",
+            "Fairness: No discrimination based on protected characteristics",
+            "Privacy: Respect user data and confidentiality",
+            "Safety: Prevent harmful outputs",
+            "Accountability: Log all decisions for audit",
+            "Beneficence: Act in the best interest of users"
+        ]
+
+    def _log_enforcement(self, result: Dict[str, Any]):
+        """Log enforcement action for audit trail."""
+        self.audit_log.append({
+            "timestamp": time.time(),
+            "passed": result["passed"],
+            "warnings": result["warnings"]
+        })
+
+        # Trim to prevent unbounded growth
+        if len(self.audit_log) > self._max_audit_entries:
+            self.audit_log = self.audit_log[-self._max_audit_entries:]
+
+    def get_audit_log(self, recent: int = 10) -> List[Dict]:
+        """Get recent audit log entries."""
+        return self.audit_log[-recent:]