nexo-brain 2.6.20 → 2.6.21

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "2.6.20",
+  "version": "2.6.21",
   "description": "Local cognitive runtime for Claude Code \u2014 persistent memory, overnight learning, doctor diagnostics, personal scripts, recovery-aware jobs, startup preflight, and optional dashboard/power helper.",
   "author": {
     "name": "NEXO Brain",

package/README.md

@@ -38,7 +38,7 @@ That means NEXO now manages not only the shared runtime and MCP wiring, but also
 - For Codex specifically, `nexo chat` and Codex headless automation inject the current bootstrap explicitly, so Codex starts as NEXO even when plain global Codex startup is inconsistent about global instructions.
 - Deep Sleep now reads both Claude Code and Codex transcript stores, so overnight analysis still works even when the user spends the day in Codex.
 
-Version `2.6.14` closes those parity gaps in practice, `2.6.15` hardens the installed-runtime migration path so existing users actually receive the managed bootstrap updates cleanly, `2.6.16` pushes the system further in three directions, `2.6.17` finishes the annoying last-mile migration bugs for real existing installs, `2.6.18` tightens the remaining practical gaps around manual Codex use, Deep Sleep horizon artifacts, and retrieval honesty, and `2.6.20` makes the recommended Claude profile explicit across installer, runtime defaults, existing installs, and the update path itself: `Opus 4.6 with 1M context`.
+Version `2.6.14` closes those parity gaps in practice, `2.6.15` hardens the installed-runtime migration path so existing users actually receive the managed bootstrap updates cleanly, `2.6.16` pushes the system further in three directions, `2.6.17` finishes the annoying last-mile migration bugs for real existing installs, `2.6.18` tightens the remaining practical gaps around manual Codex use, Deep Sleep horizon artifacts, and retrieval honesty, `2.6.20` makes the recommended Claude profile explicit across installer, runtime defaults, existing installs, and the update path itself with `Opus 4.6 with 1M context`, and `2.6.21` upgrades Deep Sleep from passive nightly analysis toward concrete engineering action.
 
 - Codex now gets managed global bootstrap/model sync in `~/.codex/config.toml`, so sessions opened outside `nexo chat` are much less likely to start as plain Codex.
 - Codex config now also persists a managed `mcp_servers.nexo` entry, so the shared brain survives even if ad-hoc Codex MCP state drifts.
@@ -47,6 +47,7 @@ Version `2.6.14` closes those parity gaps in practice, `2.6.15` hardens the inst
 - Retrieval explanations now surface confidence and the auto-strategy that fired, while associative expansion trims itself back to `top_k` instead of leaking low-signal neighbors.
 - Deep Sleep now blends recent context with older context over a 60-day horizon, and memory decay now tracks per-memory `stability` and `difficulty` instead of relying only on global decay constants.
 - Deep Sleep now also carries project-priority weighting into its long-horizon context and writes reusable weekly/monthly summary artifacts instead of reasoning only day by day.
+- Deep Sleep now semantically deduplicates followups, consolidates overlapping learnings, flags contradictory learnings for review, and backfills explicit engineering followups when recurring patterns imply a concrete fix.
 - Existing installs that already had NEXO connected to Codex now backfill that client state automatically during update/sync, so the managed Codex bootstrap actually lands without manual cleanup.
 - Bootstrap docs now fall back to the operator name `NEXO` when local metadata is blank, avoiding broken headings in `CLAUDE.md` and `AGENTS.md`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "2.6.20",
+  "version": "2.6.21",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain — Shared brain for AI agents. Persistent memory, semantic RAG, natural forgetting, metacognitive guard, trust scoring, 150+ MCP tools. Works with Claude Code, Codex, Claude Desktop & any MCP client. 100% local, free.",
   "homepage": "https://nexo-brain.com",

package/src/scripts/deep-sleep/apply_findings.py

@@ -17,10 +17,12 @@ Environment variables:
 import hashlib
 import json
 import os
+import re
 import sqlite3
 import sys
 from collections import Counter
 from datetime import datetime, timedelta
+from difflib import SequenceMatcher
 from pathlib import Path
 
 NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
@@ -34,6 +36,36 @@ COGNITIVE_DB = NEXO_HOME / "data" / "cognitive.db"
 OPERATIONS_DIR = NEXO_HOME / "operations"
 BACKUP_DIR = DEEP_SLEEP_DIR  # backups stored alongside outputs
 
+STOPWORDS = {
+    "the", "a", "an", "and", "or", "but", "with", "for", "from", "into", "onto",
+    "that", "this", "these", "those", "have", "has", "had", "will", "would",
+    "could", "should", "must", "need", "needs", "your", "their", "there", "here",
+    "about", "before", "after", "during", "through", "without", "within", "while",
+    "que", "con", "para", "por", "los", "las", "una", "uno", "sobre", "desde",
+    "cuando", "como", "pero", "todo", "toda", "cada", "into", "across", "using",
+}
+CONCRETE_ACTION_VERBS = {
+    "add", "implement", "create", "write", "build", "introduce", "enforce",
+    "automate", "validate", "check", "verify", "guard", "fix", "migrate",
+    "review", "reconcile", "pin", "sync", "instrument",
+}
+NEGATION_PATTERNS = (
+    "do not", "don't", "never", "avoid", "skip", "without", "forbid", "forbidden",
+    "disable", "disabled", "remove", "ban", "bypass",
+)
+CONTRADICTION_PAIRS = (
+    ("enable", "disable"),
+    ("use", "avoid"),
+    ("add", "remove"),
+    ("allow", "forbid"),
+    ("always", "never"),
+    ("before", "after"),
+    ("require", "skip"),
+    ("validate", "bypass"),
+    ("include", "exclude"),
+)
+TABLE_COLUMNS_CACHE: dict[tuple[str, str], set[str]] = {}
+
 
 def generate_run_id(target_date: str) -> str:
     """Generate a unique run ID for this execution."""
@@ -75,41 +107,435 @@ def backup_db(db_path: Path, run_id: str) -> Path | None:
         return None
 
 
+def _table_columns(db_path: Path, table: str) -> set[str]:
+    cache_key = (str(db_path), table)
+    if cache_key in TABLE_COLUMNS_CACHE:
+        return TABLE_COLUMNS_CACHE[cache_key]
+    if not db_path.exists():
+        TABLE_COLUMNS_CACHE[cache_key] = set()
+        return set()
+    try:
+        conn = sqlite3.connect(str(db_path))
+        rows = conn.execute(f"PRAGMA table_info({table})").fetchall()
+        conn.close()
+    except Exception:
+        TABLE_COLUMNS_CACHE[cache_key] = set()
+        return set()
+    cols = {str(row[1]) for row in rows}
+    TABLE_COLUMNS_CACHE[cache_key] = cols
+    return cols
+
+
+def _row_dict(row) -> dict:
+    if row is None:
+        return {}
+    if isinstance(row, sqlite3.Row):
+        return dict(row)
+    return dict(zip(row.keys(), row)) if hasattr(row, "keys") else dict(row)
+
+
+def _normalize_text(value: str) -> str:
+    text = str(value or "").lower()
+    text = re.sub(r"https?://\S+", " ", text)
+    text = re.sub(r"[^a-z0-9_/\-\s]+", " ", text)
+    text = re.sub(r"\s+", " ", text)
+    return text.strip()
+
+
+def _tokenize(value: str) -> list[str]:
+    tokens = re.findall(r"[a-z0-9_/-]+", _normalize_text(value))
+    return [token for token in tokens if len(token) > 2 and token not in STOPWORDS]
+
+
+def _text_similarity(left: str, right: str) -> float:
+    normalized_left = _normalize_text(left)
+    normalized_right = _normalize_text(right)
+    if not normalized_left or not normalized_right:
+        return 0.0
+    if normalized_left == normalized_right:
+        return 1.0
+
+    left_tokens = set(_tokenize(normalized_left))
+    right_tokens = set(_tokenize(normalized_right))
+    shared = left_tokens & right_tokens
+    if not shared:
+        return SequenceMatcher(None, normalized_left, normalized_right).ratio()
+
+    seq = SequenceMatcher(None, normalized_left, normalized_right).ratio()
+    jaccard = len(shared) / len(left_tokens | right_tokens) if (left_tokens or right_tokens) else 0.0
+    overlap = len(shared) / min(len(left_tokens), len(right_tokens)) if min(len(left_tokens), len(right_tokens)) else 0.0
+    containment = (
+        1.0
+        if normalized_left in normalized_right or normalized_right in normalized_left
+        else 0.0
+    )
+    return round(max((seq * 0.45) + (jaccard * 0.2) + (overlap * 0.35), overlap, (containment * 0.8) + (seq * 0.2)), 4)
+
+
+def _is_concrete_action(text: str) -> bool:
+    tokens = set(_tokenize(text))
+    return bool(tokens & CONCRETE_ACTION_VERBS)
+
+
+def _prefer_due_date(current_value, new_value) -> str:
+    current = _parse_any_datetime(current_value)
+    new = _parse_any_datetime(new_value)
+    if new and (not current or new <= current):
+        return str(new_value or "")
+    return str(current_value or "")
+
+
+def _append_note(base: str, note: str) -> str:
+    base = str(base or "").strip()
+    note = str(note or "").strip()
+    if not note:
+        return base
+    if not base:
+        return note
+    if note.lower() in base.lower():
+        return base
+    return f"{base}\n\n{note}"
+
+
+def _contains_negation(text: str) -> bool:
+    lowered = _normalize_text(text)
+    return any(token in lowered for token in NEGATION_PATTERNS)
+
+
+def _negated_action_verbs(text: str) -> set[str]:
+    lowered = _normalize_text(text)
+    matches = set()
+    for pattern in (r"(?:never|avoid|skip|disable|remove|forbid|bypass)\s+([a-z0-9_-]+)", r"(?:do not|don't)\s+([a-z0-9_-]+)"):
+        matches.update(re.findall(pattern, lowered))
+    return {match for match in matches if len(match) > 2}
+
+
+def _looks_contradictory(existing_text: str, new_text: str) -> bool:
+    existing_norm = _normalize_text(existing_text)
+    new_norm = _normalize_text(new_text)
+    if not existing_norm or not new_norm:
+        return False
+    existing_tokens = set(_tokenize(existing_norm))
+    new_tokens = set(_tokenize(new_norm))
+    if len(existing_tokens & new_tokens) < 3:
+        return False
+    existing_negated_verbs = _negated_action_verbs(existing_norm)
+    new_negated_verbs = _negated_action_verbs(new_norm)
+    if existing_negated_verbs & new_tokens and not existing_negated_verbs & new_negated_verbs:
+        return True
+    if new_negated_verbs & existing_tokens and not existing_negated_verbs & new_negated_verbs:
+        return True
+    if _contains_negation(existing_norm) != _contains_negation(new_norm):
+        return True
+    for positive, negative in CONTRADICTION_PAIRS:
+        existing_has_pair = positive in existing_norm or negative in existing_norm
+        new_has_pair = positive in new_norm or negative in new_norm
+        if existing_has_pair and new_has_pair:
+            if (positive in existing_norm and negative in new_norm) or (negative in existing_norm and positive in new_norm):
+                return True
+    return False
+
+
+def _fetch_open_followups() -> list[dict]:
+    if not NEXO_DB.exists():
+        return []
+    conn = sqlite3.connect(str(NEXO_DB))
+    conn.row_factory = sqlite3.Row
+    cols = _table_columns(NEXO_DB, "followups")
+    reasoning_sql = ", reasoning" if "reasoning" in cols else ""
+    verification_sql = ", verification" if "verification" in cols else ""
+    try:
+        rows = conn.execute(
+            "SELECT id, description, date, status"
+            f"{verification_sql}{reasoning_sql} "
+            "FROM followups WHERE status NOT LIKE 'COMPLETED%' "
+            "AND status NOT IN ('DELETED','archived','blocked','waiting','CANCELLED')"
+        ).fetchall()
+    finally:
+        conn.close()
+    return [dict(row) for row in rows]
+
+
+def _find_similar_followup(description: str, threshold: float = 0.58) -> dict | None:
+    candidates = []
+    query = str(description or "").strip()
+    if not query:
+        return None
+    query_tokens = set(_tokenize(query))
+    for row in _fetch_open_followups():
+        haystack = " ".join(
+            [
+                str(row.get("description", "") or ""),
+                str(row.get("verification", "") or ""),
+                str(row.get("reasoning", "") or ""),
+            ]
+        )
+        haystack_tokens = set(_tokenize(haystack))
+        if len(query_tokens & haystack_tokens) < 2 and _normalize_text(query) not in _normalize_text(haystack):
+            continue
+        score = _text_similarity(query, haystack)
+        if score >= threshold:
+            candidates.append({**row, "_similarity": score})
+    if not candidates:
+        return None
+    candidates.sort(key=lambda item: item["_similarity"], reverse=True)
+    return candidates[0]
+
+
+def _touch_existing_followup(existing: dict, *, description: str, date: str = "", reasoning_note: str = "") -> dict:
+    cols = _table_columns(NEXO_DB, "followups")
+    if not cols:
+        return {"success": False, "error": "followups table not found"}
+
+    updates: dict[str, object] = {}
+    existing_description = str(existing.get("description", "") or "")
+    if _is_concrete_action(description) and not _is_concrete_action(existing_description):
+        updates["description"] = description
+    preferred_date = _prefer_due_date(existing.get("date", ""), date)
+    if preferred_date and preferred_date != str(existing.get("date", "") or "") and "date" in cols:
+        updates["date"] = preferred_date
+    if "reasoning" in cols and reasoning_note:
+        updates["reasoning"] = _append_note(existing.get("reasoning", ""), reasoning_note)
+    if "updated_at" in cols:
+        updates["updated_at"] = datetime.now().timestamp()
+
+    if updates:
+        conn = sqlite3.connect(str(NEXO_DB))
+        set_clause = ", ".join(f"{column} = ?" for column in updates)
+        params = list(updates.values()) + [existing["id"]]
+        conn.execute(f"UPDATE followups SET {set_clause} WHERE id = ?", params)
+        conn.commit()
+        conn.close()
+
+    return {
+        "success": True,
+        "id": existing["id"],
+        "outcome": "matched_existing_followup",
+        "similarity": existing.get("_similarity", 1.0),
+        "updated_existing": bool(updates),
+    }
+
+
+def _fetch_learning_candidates(category: str = "") -> list[dict]:
+    if not NEXO_DB.exists():
+        return []
+    cols = _table_columns(NEXO_DB, "learnings")
+    if not cols:
+        return []
+    select_fields = ["id", "category", "title", "content", "created_at", "updated_at"]
+    for optional in ("reasoning", "prevention", "applies_to", "status", "review_due_at", "last_reviewed_at", "weight", "priority"):
+        if optional in cols:
+            select_fields.append(optional)
+    query = f"SELECT {', '.join(select_fields)} FROM learnings"
+    params: list[object] = []
+    if category and "category" in cols:
+        query += " WHERE category = ?"
+        params.append(category)
+    query += " ORDER BY COALESCE(updated_at, created_at) DESC LIMIT 240"
+    conn = sqlite3.connect(str(NEXO_DB))
+    conn.row_factory = sqlite3.Row
+    try:
+        rows = conn.execute(query, tuple(params)).fetchall()
+    finally:
+        conn.close()
+    return [dict(row) for row in rows]
+
+
+def _find_learning_match(category: str, title: str, content: str) -> dict | None:
+    candidates = []
+    new_text = " ".join([str(title or ""), str(content or "")]).strip()
+    for row in _fetch_learning_candidates(category):
+        existing_text = " ".join([str(row.get("title", "") or ""), str(row.get("content", "") or "")])
+        similarity = _text_similarity(new_text, existing_text)
+        if similarity < 0.58:
+            continue
+        contradiction = _looks_contradictory(existing_text, new_text)
+        candidates.append({**row, "_similarity": similarity, "_contradiction": contradiction})
+    if not candidates:
+        return None
+    candidates.sort(
+        key=lambda item: (item["_contradiction"], item["_similarity"], item.get("updated_at", 0) or item.get("created_at", 0)),
+        reverse=True,
+    )
+    return candidates[0]
+
+
+def _update_learning_row(learning_id: int, updates: dict[str, object]) -> None:
+    if not updates:
+        return
+    conn = sqlite3.connect(str(NEXO_DB))
+    set_clause = ", ".join(f"{column} = ?" for column in updates)
+    conn.execute(f"UPDATE learnings SET {set_clause} WHERE id = ?", list(updates.values()) + [learning_id])
+    conn.commit()
+    conn.close()
+
+
+def _bump_weight(existing_value, amount: float) -> float:
+    try:
+        base = float(existing_value or 0)
+    except Exception:
+        base = 0.0
+    return round(min(10.0, base + amount), 2)
+
+
+def _flag_learning_contradiction(existing: dict, category: str, title: str, content: str) -> dict:
+    review_description = (
+        f"Reconcile contradictory learning in {category or 'general'}: "
+        f"review existing learning #{existing.get('id')} ('{existing.get('title', '')}') "
+        f"against new Deep Sleep finding '{title}'. Produce one canonical rule, update guardrails, and remove ambiguity."
+    )
+    followup_result = create_followup(
+        description=review_description,
+        date="",
+        reasoning_note=f"Contradiction detected against learning #{existing.get('id')}: {content[:240]}",
+    )
+    return {
+        "success": followup_result.get("success", False),
+        "id": existing.get("id"),
+        "outcome": "contradiction_review",
+        "similarity": existing.get("_similarity", 0.0),
+        "review_followup_id": followup_result.get("id"),
+        "followup_result": followup_result,
+    }
+
+
 def add_learning(category: str, title: str, content: str) -> dict:
     """Add a learning to nexo.db. Returns result dict."""
     if not NEXO_DB.exists():
         return {"success": False, "error": "nexo.db not found"}
     try:
+        existing = _find_learning_match(category, title, content)
+        if existing:
+            similarity = existing.get("_similarity", 0.0)
+            if existing.get("_contradiction"):
+                return _flag_learning_contradiction(existing, category, title, content)
+
+            updates: dict[str, object] = {}
+            columns = _table_columns(NEXO_DB, "learnings")
+            if "updated_at" in columns:
+                updates["updated_at"] = datetime.now().timestamp()
+
+            existing_title = _normalize_text(existing.get("title", ""))
+            existing_content = _normalize_text(existing.get("content", ""))
+            incoming_title = _normalize_text(title)
+            incoming_content = _normalize_text(content)
+
+            if similarity >= 0.95 and (
+                existing_title == incoming_title
+                or existing_content == incoming_content
+                or incoming_content in existing_content
+                or existing_content in incoming_content
+            ):
+                if "weight" in columns:
+                    updates["weight"] = _bump_weight(existing.get("weight"), 0.1)
+                if "last_reviewed_at" in columns:
+                    updates["last_reviewed_at"] = datetime.now().timestamp()
+                if "reasoning" in columns:
+                    updates["reasoning"] = _append_note(
+                        existing.get("reasoning", ""),
+                        f"Reconfirmed by Deep Sleep on {datetime.now().strftime('%Y-%m-%d')}.",
+                    )
+                _update_learning_row(existing["id"], updates)
+                return {
+                    "success": True,
+                    "id": existing["id"],
+                    "outcome": "duplicate_learning",
+                    "similarity": similarity,
+                    "updated_existing": bool(updates),
+                }
+
+            if similarity >= 0.58:
+                if "weight" in columns:
+                    updates["weight"] = _bump_weight(existing.get("weight"), 0.25)
+                if "reasoning" in columns:
+                    updates["reasoning"] = _append_note(
+                        existing.get("reasoning", ""),
+                        f"Deep Sleep reinforcement ({datetime.now().strftime('%Y-%m-%d')}): {title}. {content[:240]}",
+                    )
+                elif "content" in columns and content and content not in str(existing.get("content", "")):
+                    updates["content"] = _append_note(
+                        existing.get("content", ""),
+                        f"Reinforced by Deep Sleep: {content[:240]}",
+                    )
+                _update_learning_row(existing["id"], updates)
+                return {
+                    "success": True,
+                    "id": existing["id"],
+                    "outcome": "reinforced_learning",
+                    "similarity": similarity,
+                    "updated_existing": bool(updates),
+                }
+
         now = datetime.now().timestamp()
+        columns = _table_columns(NEXO_DB, "learnings")
+        payload = {
+            "category": category,
+            "title": title,
+            "content": content,
+            "created_at": now,
+            "updated_at": now,
+        }
+        if "reasoning" in columns:
+            payload["reasoning"] = "Deep Sleep v2 overnight analysis"
+        if "status" in columns:
+            payload["status"] = "active"
+        insert_columns = [column for column in payload if column in columns]
+        values = [payload[column] for column in insert_columns]
+
         conn = sqlite3.connect(str(NEXO_DB))
         cursor = conn.execute(
-            "INSERT INTO learnings (category, title, content, created_at, updated_at, reasoning) VALUES (?, ?, ?, ?, ?, ?)",
-            (category, title, content, now, now, "Deep Sleep v2 overnight analysis")
+            f"INSERT INTO learnings ({', '.join(insert_columns)}) VALUES ({', '.join('?' for _ in insert_columns)})",
+            values,
         )
         learning_id = cursor.lastrowid
         conn.commit()
         conn.close()
-        return {"success": True, "id": learning_id}
+        return {"success": True, "id": learning_id, "outcome": "new_learning"}
     except Exception as e:
         return {"success": False, "error": str(e)}
 
 
-def create_followup(description: str, date: str = "") -> dict:
+def create_followup(description: str, date: str = "", reasoning_note: str = "") -> dict:
     """Create a followup in nexo.db. Returns result dict."""
     if not NEXO_DB.exists():
         return {"success": False, "error": "nexo.db not found"}
     try:
+        matched = _find_similar_followup(description)
+        if matched:
+            return _touch_existing_followup(
+                matched,
+                description=description,
+                date=date,
+                reasoning_note=reasoning_note or "Deep Sleep matched this followup semantically.",
+            )
+
         now = datetime.now().timestamp()
         # Generate a deterministic ID
         fid = "NF-DS-" + hashlib.md5(description.encode()).hexdigest()[:8].upper()
+        columns = _table_columns(NEXO_DB, "followups")
+        payload = {
+            "id": fid,
+            "description": description,
+            "date": date,
+            "status": "PENDING",
+            "created_at": now,
+            "updated_at": now,
+        }
+        if "reasoning" in columns:
+            payload["reasoning"] = reasoning_note or "Deep Sleep v2 overnight analysis"
+        if "verification" in columns:
+            payload["verification"] = ""
+        insert_columns = [column for column in payload if column in columns]
+        values = [payload[column] for column in insert_columns]
+
         conn = sqlite3.connect(str(NEXO_DB))
         conn.execute(
-            "INSERT OR IGNORE INTO followups (id, description, date, status, created_at, updated_at, reasoning) VALUES (?, ?, ?, 'PENDING', ?, ?, ?)",
-            (fid, description, date, now, now, "Deep Sleep v2 overnight analysis")
+            f"INSERT OR IGNORE INTO followups ({', '.join(insert_columns)}) VALUES ({', '.join('?' for _ in insert_columns)})",
+            values,
         )
         conn.commit()
         conn.close()
-        return {"success": True, "id": fid}
+        return {"success": True, "id": fid, "outcome": "new_followup"}
     except Exception as e:
         return {"success": False, "error": str(e)}
 
@@ -964,7 +1390,8 @@ def apply_action(action: dict, run_id: str) -> dict:
     elif action_type == "followup_create":
         result = create_followup(
             description=content.get("description", content.get("title", "")),
-            date=content.get("date", "")
+            date=content.get("date", ""),
+            reasoning_note=content.get("reasoning", content.get("why", "")),
         )
         log_entry["status"] = "applied" if result.get("success") else "error"
         log_entry["details"] = result

package/src/scripts/deep-sleep/synthesize-prompt.md

@@ -30,6 +30,15 @@ Synthesize across all sessions:
 - Cross-domain connections where an older learning or session sample explains a current issue
 - Topics repeatedly mentioned over time but never formalized into a learning or followup
 - Project pressure that is rising because of repeated diary mentions, open followups, or adverse outcomes
+- For medium/high-severity patterns, propose a concrete fix artifact:
+  - script
+  - hook
+  - checklist
+  - validation step
+  - workflow change
+  - guardrail
+
+Do not stop at diagnosis. Turn repeated problems into concrete engineering work.
 
 ### 2. Morning Agenda
 Generate a prioritized agenda for the next morning:
@@ -126,6 +135,14 @@ Merge and deduplicate all findings into a final action list. Each action should
 - `dedupe_key`: deterministic key for idempotency
 - `content`: the actual data to write
 
+When generating `followup_create`, prefer descriptions that start with a concrete verb and include the deliverable:
+- "Add a pre-release validation script ..."
+- "Implement a guard hook that ..."
+- "Create a checklist for ..."
+- "Write a watchdog check that ..."
+
+Avoid vague followups that merely restate the diagnosis.
+
 ## Output Format
 
 Return ONLY valid JSON. No markdown code fences. No explanation text.
@@ -140,6 +157,12 @@ Return ONLY valid JSON. No markdown code fences. No explanation text.
       "pattern": "Description of the pattern",
       "sessions": ["session1.jsonl", "session2.jsonl"],
       "severity": "low|medium|high",
+      "proposed_fix": {
+        "title": "Short concrete fix title",
+        "description": "Concrete engineering change to make",
+        "deliverable": "script|hook|checklist|workflow|guardrail",
+        "confidence": 0.0
+      },
       "evidence": [
         {"type": "transcript", "session_id": "...", "message_index": 42, "quote": "..."}
       ]

package/src/scripts/deep-sleep/synthesize.py

@@ -14,6 +14,7 @@ import json
 import os
 import subprocess
 import sys
+import hashlib
 from datetime import datetime
 from pathlib import Path
 
@@ -28,6 +29,7 @@ if str(NEXO_CODE) not in sys.path:
 from agent_runner import AutomationBackendUnavailableError, run_automation_prompt
 
 CLAUDE_TIMEOUT = 21600  # 3h safety net (prevents zombie processes)
+ACTION_VERBS = {"add", "implement", "create", "write", "build", "enforce", "automate", "validate", "guard", "fix", "review"}
 
 
 def extract_json_from_response(text: str) -> dict | None:
@@ -86,6 +88,96 @@ def collect_skill_runtime_candidates(target_date: str) -> tuple[Path, dict]:
     return output_file, payload
 
 
+def _normalize_action_text(value: str) -> str:
+    return " ".join(str(value or "").strip().lower().split())
+
+
+def _looks_concrete_action(text: str) -> bool:
+    words = {word.strip(".,:;()[]{}").lower() for word in str(text or "").split()}
+    return bool(words & ACTION_VERBS)
+
+
+def _pattern_followup_from_fix(pattern: dict) -> dict | None:
+    severity = str(pattern.get("severity", "") or "").lower()
+    sessions = pattern.get("sessions", []) or []
+    if severity not in {"medium", "high"} and len(sessions) < 2:
+        return None
+
+    proposed_fix = pattern.get("proposed_fix") or {}
+    pattern_text = str(pattern.get("pattern", "") or "").strip()
+    title = str(proposed_fix.get("title", "") or "").strip()
+    description = str(proposed_fix.get("description", "") or "").strip()
+    deliverable = str(proposed_fix.get("deliverable", "") or proposed_fix.get("artifact", "") or "").strip()
+
+    if title and description:
+        if _looks_concrete_action(description):
+            followup_description = description
+        else:
+            followup_description = f"{title}: {description}"
+    elif description:
+        followup_description = description
+    elif title:
+        followup_description = title
+    elif pattern_text:
+        followup_description = (
+            f"Implement a concrete guardrail for recurring issue: {pattern_text}. "
+            "Deliverable should be a script, hook, checklist, or automated validation that prevents the same failure from repeating."
+        )
+    else:
+        return None
+
+    if deliverable and deliverable.lower() not in followup_description.lower():
+        followup_description = f"{followup_description} Deliverable: {deliverable}."
+    if not _looks_concrete_action(followup_description):
+        followup_description = f"Implement this fix: {followup_description}"
+
+    return {
+        "action_type": "followup_create",
+        "action_class": "auto_apply" if severity == "high" else "draft_for_morning",
+        "confidence": round(max(float(proposed_fix.get("confidence", 0.0) or 0.0), 0.86 if severity == "high" else 0.78), 2),
+        "impact": "high" if severity == "high" else "medium",
+        "reversibility": "reversible",
+        "evidence": pattern.get("evidence", []) or [],
+        "dedupe_key": "engineering-fix:" + hashlib.md5(
+            _normalize_action_text(followup_description).encode("utf-8")
+        ).hexdigest()[:16],
+        "content": {
+            "title": title or f"Engineering fix for: {pattern_text[:90]}",
+            "description": followup_description,
+            "date": "",
+            "reasoning": f"Deep Sleep engineering followup from recurring pattern: {pattern_text}",
+        },
+    }
+
+
+def backfill_engineering_actions(payload: dict) -> dict:
+    if not isinstance(payload, dict):
+        return payload
+    actions = payload.get("actions")
+    if not isinstance(actions, list):
+        actions = []
+        payload["actions"] = actions
+
+    existing_keys = {str(action.get("dedupe_key", "") or "") for action in actions}
+    existing_descriptions = {
+        _normalize_action_text(action.get("content", {}).get("description", ""))
+        for action in actions
+        if isinstance(action, dict)
+    }
+
+    for pattern in payload.get("cross_session_patterns", []) or []:
+        action = _pattern_followup_from_fix(pattern)
+        if not action:
+            continue
+        description = _normalize_action_text(action["content"]["description"])
+        if action["dedupe_key"] in existing_keys or description in existing_descriptions:
+            continue
+        actions.append(action)
+        existing_keys.add(action["dedupe_key"])
+        existing_descriptions.add(description)
+    return payload
+
+
 def main():
     target_date = sys.argv[1] if len(sys.argv) > 1 else datetime.now().strftime("%Y-%m-%d")
 
@@ -177,6 +269,8 @@ def main():
             print(f"[synthesize] Failed to parse JSON. Raw output saved to {debug_file}", file=sys.stderr)
             sys.exit(1)
 
+        parsed = backfill_engineering_actions(parsed)
+
         # Write synthesis output
         output_file = DEEP_SLEEP_DIR / f"{target_date}-synthesis.json"
         with open(output_file, "w") as f:

package/templates/nexo_helper.py

@@ -16,6 +16,36 @@ from pathlib import Path
 
 
 NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+DEFAULT_ALLOWED_TOOLS = "Read,Write,Edit,Glob,Grep,Bash,mcp__nexo__*"
+
+
+def _load_schedule() -> dict:
+    schedule_path = NEXO_HOME / "config" / "schedule.json"
+    if not schedule_path.is_file():
+        return {}
+    try:
+        return json.loads(schedule_path.read_text())
+    except Exception:
+        return {}
+
+
+def _resolve_automation_backend() -> str:
+    data = _load_schedule()
+    return str(data.get("automation_backend", "claude_code") or "claude_code")
+
+
+def _load_bootstrap_prompt() -> str:
+    backend = _resolve_automation_backend()
+    if backend == "codex":
+        path = Path.home() / ".codex" / "AGENTS.md"
+    else:
+        path = Path.home() / ".claude" / "CLAUDE.md"
+    if not path.is_file():
+        return ""
+    try:
+        return path.read_text()
+    except Exception:
+        return ""
 
 
 def run_nexo(args: list[str]) -> str:
@@ -57,6 +87,9 @@ def run_automation_text(
     model: str = "",
     reasoning_effort: str = "",
     cwd: str = "",
+    allowed_tools: str = DEFAULT_ALLOWED_TOOLS,
+    append_system_prompt: str = "",
+    include_bootstrap: bool = True,
 ) -> str:
     """Run the configured NEXO automation backend and return text output.
 
@@ -75,6 +108,17 @@ def run_automation_text(
         cmd.extend(["--reasoning-effort", reasoning_effort])
     if cwd:
         cmd.extend(["--cwd", cwd])
+    merged_system_prompt = []
+    if include_bootstrap:
+        bootstrap = _load_bootstrap_prompt()
+        if bootstrap:
+            merged_system_prompt.append(bootstrap)
+    if append_system_prompt:
+        merged_system_prompt.append(append_system_prompt)
+    if merged_system_prompt:
+        cmd.extend(["--append-system-prompt", "\n\n".join(merged_system_prompt)])
+    if allowed_tools:
+        cmd.extend(["--allowed-tools", allowed_tools])
 
     env = os.environ.copy()
     env.setdefault("NEXO_HOME", str(NEXO_HOME))