nexo-brain 5.3.11 → 5.3.12

package/src/plugins/doctor.py

@@ -11,13 +11,14 @@ if str(SRC_DIR) not in sys.path:
     sys.path.insert(0, str(SRC_DIR))
 
 
-def handle_doctor(tier: str = "boot", fix: bool = False, output: str = "text") -> str:
+def handle_doctor(tier: str = "boot", fix: bool = False, output: str = "text", plane: str = "") -> str:
     """Unified diagnostic report for boot/runtime/deep health.
 
     Args:
         tier: Diagnostic tier — boot, runtime, deep, or all (default: boot)
         fix: Apply deterministic fixes (default: False)
         output: Output format — text or json (default: text)
+        plane: Diagnostic plane — runtime_personal, installation_live, or database_real
     """
     from doctor.orchestrator import run_doctor
     from doctor.formatters import format_report
@@ -27,7 +28,7 @@ def handle_doctor(tier: str = "boot", fix: bool = False, output: str = "text") -
     if output not in ("text", "json"):
         return f"Invalid output '{output}'. Use: text, json"
 
-    report = run_doctor(tier=tier, fix=fix)
+    report = run_doctor(tier=tier, fix=fix, plane=plane)
     return format_report(report, fmt=output)
 
 

package/src/plugins/schedule.py

@@ -20,6 +20,9 @@ from script_registry import (
     get_declared_schedule,
 )
 
+LEGACY_BACKUP_CRON_ID = "backup"
+LEGACY_BACKUP_SUMMARY = "legacy backup file evidence"
+
 
 def handle_schedule_status(hours: int = 24, cron_id: str = '') -> str:
     """Show cron execution status — what ran, what failed, durations.
@@ -30,6 +33,8 @@ def handle_schedule_status(hours: int = 24, cron_id: str = '') -> str:
     """
     if cron_id:
         runs = cron_runs_recent(hours, cron_id)
+        if cron_id == LEGACY_BACKUP_CRON_ID:
+            runs = _select_backup_runs(runs, hours)
         if not runs:
             return f"No runs for '{cron_id}' in the last {hours}h."
         schedule_meta = get_personal_script_schedule(cron_id) or {}
@@ -53,7 +58,7 @@ def handle_schedule_status(hours: int = 24, cron_id: str = '') -> str:
         return "\n".join(lines)
 
     # Summary view — one line per cron
-    summary = cron_runs_summary(hours)
+    summary = _merge_legacy_summaries(cron_runs_summary(hours), hours)
     if not summary:
         return f"No cron executions recorded in the last {hours}h."
 
@@ -82,6 +87,119 @@ def handle_schedule_status(hours: int = 24, cron_id: str = '') -> str:
     return "\n".join(lines)
 
 
+def _select_backup_runs(db_runs: list[dict], hours: int) -> list[dict]:
+    legacy_runs = _legacy_backup_runs(hours)
+    if _prefer_legacy_over_db(db_runs, legacy_runs):
+        return legacy_runs
+    return db_runs
+
+
+def _merge_legacy_summaries(summary_rows: list[dict], hours: int) -> list[dict]:
+    rows = [dict(row) for row in (summary_rows or [])]
+    legacy_summary = _legacy_backup_summary(hours)
+    if not legacy_summary:
+        return rows
+    by_cron_id = {row["cron_id"]: row for row in rows}
+    existing = by_cron_id.get(LEGACY_BACKUP_CRON_ID)
+    if _prefer_legacy_summary(existing, legacy_summary):
+        by_cron_id[LEGACY_BACKUP_CRON_ID] = legacy_summary
+    return sorted(
+        by_cron_id.values(),
+        key=lambda row: row.get("last_run") or "",
+        reverse=True,
+    )
+
+
+def _prefer_legacy_over_db(db_runs: list[dict], legacy_runs: list[dict]) -> bool:
+    if not legacy_runs:
+        return False
+    if not db_runs:
+        return True
+    latest_db = _parse_db_timestamp(db_runs[0].get("started_at"))
+    latest_legacy = _parse_db_timestamp(legacy_runs[0].get("started_at"))
+    if latest_legacy is None:
+        return False
+    if latest_db is None:
+        return True
+    return latest_legacy > latest_db
+
+
+def _prefer_legacy_summary(existing: dict | None, legacy: dict) -> bool:
+    if not legacy:
+        return False
+    if not existing:
+        return True
+    latest_existing = _parse_db_timestamp(existing.get("last_run"))
+    latest_legacy = _parse_db_timestamp(legacy.get("last_run"))
+    if latest_legacy is None:
+        return False
+    if latest_existing is None:
+        return True
+    return latest_legacy > latest_existing
+
+
+def _legacy_backup_summary(hours: int) -> dict | None:
+    runs = _legacy_backup_runs(hours)
+    if not runs:
+        return None
+    return _build_summary_from_runs(LEGACY_BACKUP_CRON_ID, runs)
+
+
+def _legacy_backup_runs(hours: int) -> list[dict]:
+    nexo_home = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+    backup_dir = nexo_home / "backups"
+    if not backup_dir.exists():
+        return []
+    cutoff = _now_utc().timestamp() - (hours * 3600)
+    runs: list[dict] = []
+    for backup_file in backup_dir.glob("nexo-*.db"):
+        try:
+            stat = backup_file.stat()
+        except OSError:
+            continue
+        if stat.st_mtime < cutoff:
+            continue
+        started = datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc).replace(microsecond=0)
+        started_at = started.strftime("%Y-%m-%d %H:%M:%S")
+        runs.append(
+            {
+                "cron_id": LEGACY_BACKUP_CRON_ID,
+                "started_at": started_at,
+                "ended_at": started_at,
+                "exit_code": 0,
+                "summary": LEGACY_BACKUP_SUMMARY,
+                "error": "",
+                "duration_secs": 1.0,
+            }
+        )
+    runs.sort(key=lambda row: row["started_at"], reverse=True)
+    return runs
+
+
+def _build_summary_from_runs(cron_id: str, runs: list[dict]) -> dict:
+    completed_runs = [
+        row for row in runs if row.get("exit_code") is not None and row.get("ended_at")
+    ]
+    duration_values = [
+        float(row["duration_secs"])
+        for row in completed_runs
+        if row.get("duration_secs") is not None
+    ]
+    return {
+        "cron_id": cron_id,
+        "total_runs": len(runs),
+        "succeeded": sum(1 for row in completed_runs if row.get("exit_code") == 0),
+        "completed_runs": len(completed_runs),
+        "failed": sum(1 for row in completed_runs if row.get("exit_code") not in (None, 0)),
+        "open_runs": len(runs) - len(completed_runs),
+        "avg_duration": round(sum(duration_values) / len(duration_values), 1) if duration_values else None,
+        "last_run": runs[0].get("started_at"),
+        "last_exit_code": runs[0].get("exit_code"),
+        "last_ended_at": runs[0].get("ended_at"),
+        "last_summary": next((row.get("summary") for row in runs if row.get("summary")), ""),
+    }
+
+
 def _summary_has_warning(summary: str = "") -> bool:
     lowered = str(summary or "").strip().lower()
     if not lowered:

package/src/runtime_power.py

@@ -67,8 +67,9 @@ MACOS_FDA_PROBE_PATHS = (
 )
 DEFAULT_CLAUDE_CODE_MODEL = "claude-opus-4-6[1m]"
 DEFAULT_CLAUDE_CODE_REASONING_EFFORT = ""
-DEFAULT_CODEX_MODEL = "gpt-5.4"
-DEFAULT_CODEX_REASONING_EFFORT = "xhigh"
+# Codex defaults mirror the user's primary model — no hardcoded third-party models.
+DEFAULT_CODEX_MODEL = DEFAULT_CLAUDE_CODE_MODEL
+DEFAULT_CODEX_REASONING_EFFORT = ""
 
 
 def _schedule_defaults() -> dict:

package/src/scripts/nexo-cortex-cycle.py

@@ -18,9 +18,9 @@ What this script does (idempotent and best-effort):
 3. Detects degradation signals on the 7-day window. The criteria are
    intentionally conservative to avoid false alarms on small samples:
      a. recommendation_accept_rate < 50% AND total_evaluations >= 10
-     b. linked_outcome_success_rate < 50% AND linked_outcomes_total >= 5
+     b. linked_outcome_success_rate < 50% AND linked_outcomes_resolved >= 5
      c. override_success_rate > recommended_success_rate by >= 20pp
-        AND linked_outcomes_total >= 5
+        AND linked_outcomes_resolved >= 5
 4. Opens (or refreshes) NF-CORTEX-QUALITY-DROP followup with the offending
    metrics when degradation is detected. Idempotent: if a non-PENDING /
    resolved followup of the same id already exists, it is updated in
@@ -96,6 +96,13 @@ def detect_quality_signals(summary: dict) -> list[dict]:
     total = int(summary.get("total_evaluations") or 0)
     accept_rate = float(summary.get("recommendation_accept_rate") or 0.0)
     linked_total = int(summary.get("linked_outcomes_total") or 0)
+    linked_met = int(summary.get("linked_outcomes_met") or 0)
+    linked_missed = int(summary.get("linked_outcomes_missed") or 0)
+    linked_pending = int(summary.get("linked_outcomes_pending") or 0)
+    linked_resolved = linked_met + linked_missed
+    if linked_resolved <= 0 and linked_total > 0:
+        # Older callers may omit the met/missed counters; fall back to total minus pending.
+        linked_resolved = max(0, linked_total - linked_pending)
     linked_success = float(summary.get("linked_outcome_success_rate") or 0.0)
     recommended_success = float(summary.get("recommended_success_rate") or 0.0)
     override_success = float(summary.get("override_success_rate") or 0.0)
@@ -114,21 +121,25 @@ def detect_quality_signals(summary: dict) -> list[dict]:
             ),
         })
 
-    if linked_total >= LINKED_MIN_SAMPLE and linked_success < LINKED_SUCCESS_FLOOR:
+    linked_scope = f"{linked_resolved} resolved linked outcomes"
+    if linked_pending > 0:
+        linked_scope += f" ({linked_total} total, {linked_pending} pending)"
+
+    if linked_resolved >= LINKED_MIN_SAMPLE and linked_success < LINKED_SUCCESS_FLOOR:
         signals.append({
             "kind": "linked_success",
             "severity": "warn",
             "metric_value": linked_success,
             "threshold": LINKED_SUCCESS_FLOOR,
-            "sample_size": linked_total,
+            "sample_size": linked_resolved,
             "message": (
                 f"Cortex linked-outcome success rate {linked_success:.1f}% on "
-                f"{linked_total} linked outcomes is below the "
+                f"{linked_scope} is below the "
                 f"{LINKED_SUCCESS_FLOOR:.0f}% floor."
             ),
         })
 
-    if linked_total >= LINKED_MIN_SAMPLE:
+    if linked_resolved >= LINKED_MIN_SAMPLE:
         gap = override_success - recommended_success
         if gap >= OVERRIDE_GAP_THRESHOLD:
             signals.append({
@@ -136,12 +147,12 @@ def detect_quality_signals(summary: dict) -> list[dict]:
                 "severity": "error",
                 "metric_value": gap,
                 "threshold": OVERRIDE_GAP_THRESHOLD,
-                "sample_size": linked_total,
+                "sample_size": linked_resolved,
                 "message": (
                     f"Cortex overrides outperform recommendations by {gap:.1f}pp "
                     f"(override {override_success:.1f}% vs recommended "
-                    f"{recommended_success:.1f}% on {linked_total} linked "
-                    "outcomes). The recommender is mis-ranking choices."
+                    f"{recommended_success:.1f}% on {linked_scope}). The "
+                    "recommender is mis-ranking choices."
                 ),
             })
 
@@ -171,15 +182,37 @@ def _upsert_quality_followup(signals: list[dict]) -> str:
     resolved, a fresh row is inserted with the same id (REPLACE) so the
     new degradation pattern is visible.
     """
-    if not signals:
-        return "no_signal"
-
     try:
-        from db import get_followup, get_db
+        from db import complete_followup, get_followup, get_db
     except Exception as e:
         _log(f"WARN: cannot import db helpers: {e}")
         return "skipped_no_db"
 
+    try:
+        existing = get_followup(FOLLOWUP_ID)
+    except Exception as e:
+        _log(f"WARN: get_followup raised: {e}")
+        existing = None
+
+    if not signals:
+        if not existing:
+            return "no_signal"
+        status = str(existing.get("status") or "").upper()
+        if status.startswith("COMPLETED") or status in {"DELETED", "ARCHIVED", "BLOCKED", "WAITING", "CANCELLED"}:
+            return "no_signal"
+        try:
+            complete_followup(
+                FOLLOWUP_ID,
+                result=(
+                    "Auto-resolved by cortex-cycle: no active degradation signals in the "
+                    "current 7d window."
+                ),
+            )
+        except Exception as e:
+            _log(f"WARN: failed to close followup: {e}")
+            return "failed_close"
+        return "closed"
+
     summary_lines = ["Cortex continuous validation found quality degradation:"]
     for sig in signals:
         summary_lines.append(
@@ -197,12 +230,6 @@ def _upsert_quality_followup(signals: list[dict]) -> str:
     )
     now_epoch = datetime.now().timestamp()
 
-    try:
-        existing = get_followup(FOLLOWUP_ID)
-    except Exception as e:
-        _log(f"WARN: get_followup raised: {e}")
-        existing = None
-
     try:
         conn = get_db()
         conn.execute(
@@ -255,8 +282,8 @@ def run() -> int:
             f"signals={len(signals)}"
         )
 
-    if signals:
-        action = _upsert_quality_followup(signals)
+    action = _upsert_quality_followup(signals)
+    if signals or action not in {"no_signal"}:
         _log(f"Cortex cycle: followup {FOLLOWUP_ID} {action} ({len(signals)} signal(s))")
 
     return 0

package/src/scripts/nexo-daily-self-audit.py

@@ -479,6 +479,43 @@ def _upsert_workflow_goal_inline(conn: sqlite3.Connection, *, area: str, sample_
 
     columns = _table_columns(conn, "workflow_goals")
     signature = _topic_signature(sample_goal)
+    goal_id = f"WG-AUDIT-{hashlib.sha1(f'{area}:{signature or sample_goal}'.encode('utf-8'), usedforsecurity=False).hexdigest()[:8].upper()}"
+
+    def _write_goal(existing_row: sqlite3.Row, *, reactivated: bool) -> dict:
+        updates: dict[str, object] = {}
+        if "title" in columns:
+            updates["title"] = sample_goal[:140]
+        if "objective" in columns:
+            updates["objective"] = objective
+        if "priority" in columns:
+            updates["priority"] = "high"
+        if "owner" in columns:
+            updates["owner"] = AUDIT_GOAL_OWNER
+        if "next_action" in columns:
+            updates["next_action"] = next_action
+        if "success_signal" in columns:
+            updates["success_signal"] = success_signal
+        if "shared_state" in columns:
+            updates["shared_state"] = json.dumps({"area": area, "signature": signature, "source": "self-audit"})
+        if reactivated and "status" in columns:
+            updates["status"] = "active"
+        if reactivated and "blocker_reason" in columns:
+            updates["blocker_reason"] = ""
+        if reactivated and "closed_at" in columns:
+            updates["closed_at"] = None
+        if "updated_at" in columns:
+            updates["updated_at"] = now_iso
+        assignments = ", ".join(f"{column} = ?" for column in updates)
+        conn.execute(
+            f"UPDATE workflow_goals SET {assignments} WHERE goal_id = ?",
+            [updates[column] for column in updates] + [existing_row["goal_id"]],
+        )
+        return {
+            "ok": True,
+            "action": "reactivated" if reactivated else "updated",
+            "goal_id": str(existing_row["goal_id"]),
+        }
+
     rows = conn.execute(
         """SELECT * FROM workflow_goals
            WHERE status NOT IN ('completed', 'cancelled', 'abandoned')
@@ -499,31 +536,21 @@ def _upsert_workflow_goal_inline(conn: sqlite3.Connection, *, area: str, sample_
     next_action = AUDIT_GOAL_NEXT_ACTION
     success_signal = "The theme stops resurfacing in unresolved protocol tasks."
     now_iso = datetime.now().isoformat(timespec="seconds")
-    if existing:
-        updates: dict[str, object] = {}
-        if "title" in columns:
-            updates["title"] = sample_goal[:140]
-        if "objective" in columns:
-            updates["objective"] = objective
-        if "priority" in columns:
-            updates["priority"] = "high"
-        if "owner" in columns:
-            updates["owner"] = AUDIT_GOAL_OWNER
-        if "next_action" in columns:
-            updates["next_action"] = next_action
-        if "success_signal" in columns:
-            updates["success_signal"] = success_signal
-        if "updated_at" in columns:
-            updates["updated_at"] = now_iso
-        assignments = ", ".join(f"{column} = ?" for column in updates)
-        conn.execute(
-            f"UPDATE workflow_goals SET {assignments} WHERE goal_id = ?",
-            [updates[column] for column in updates] + [existing["goal_id"]],
+    exact = conn.execute(
+        "SELECT * FROM workflow_goals WHERE goal_id = ? LIMIT 1",
+        (goal_id,),
+    ).fetchone()
+    if exact is not None:
+        exact_status = str(exact["status"] or "").lower()
+        return _write_goal(
+            exact,
+            reactivated=exact_status in {"completed", "cancelled", "abandoned"},
         )
-        return {"ok": True, "action": "updated", "goal_id": str(existing["goal_id"])}
+
+    if existing:
+        return _write_goal(existing, reactivated=False)
 
     # Content fingerprint, not security-sensitive.
-    goal_id = f"WG-AUDIT-{hashlib.sha1(f'{area}:{signature or sample_goal}'.encode('utf-8'), usedforsecurity=False).hexdigest()[:8].upper()}"
     values: dict[str, object] = {"goal_id": goal_id}
     if "session_id" in columns:
         values["session_id"] = ""

package/src/scripts/rehydrate_learnings_from_archive.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+"""Rehydrate archived markdown learnings back into the NEXO learnings table.
+
+The original Evolution #5 incident found an empty learnings table while the
+historical archive still existed as markdown grouped by domain. This helper
+parses the archive format used in those files:
+
+- markdown tables with `Error | Solucion`
+- dated sections with bullet/numbered operational learnings
+
+Dry-run is the default. Pass `--apply` to insert missing learnings.
+"""
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+REPO_SRC = Path(__file__).resolve().parents[1]
+if str(REPO_SRC) not in sys.path:
+    sys.path.insert(0, str(REPO_SRC))
+
+from db import create_learning, get_db, init_db  # noqa: E402
+from runtime_home import export_resolved_nexo_home  # noqa: E402
+
+NEXO_HOME = export_resolved_nexo_home()
+TABLE_HEADER_TITLES = {"error", "problema", "issue"}
+DEFAULT_ARCHIVE_DIRS = (
+    NEXO_HOME / "claude" / "operations" / "archive" / "learnings",
+    Path.home() / "claude" / "operations" / "archive" / "learnings",
+    Path.home() / ".claude" / "operations" / "archive" / "learnings",
+)
+
+
+@dataclass(frozen=True)
+class LearningCandidate:
+    category: str
+    title: str
+    content: str
+    reasoning: str
+    prevention: str
+    status: str = "active"
+
+
+def _strip_markdown(text: str) -> str:
+    text = text.replace("**", "").replace("__", "")
+    text = text.replace("~~", "")
+    text = re.sub(r"`([^`]*)`", r"\1", text)
+    text = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", text)
+    text = re.sub(r"\s+", " ", text).strip(" |")
+    return text.strip()
+
+
+def _derive_title(text: str) -> str:
+    first_sentence = re.split(r"(?<=[.!?])\s+", text, maxsplit=1)[0].strip()
+    if not first_sentence:
+        first_sentence = text.strip()
+    return first_sentence[:180].rstrip(" .")
+
+
+def _derive_prevention(text: str) -> str:
+    match = re.search(r"(Regla:\s*.*|SIEMPRE\s+.*|NUNCA\s+.*)", text, flags=re.IGNORECASE)
+    if match:
+        return match.group(1).strip()
+    return text[:500].strip()
+
+
+def _candidate_reasoning(path: Path, section: str) -> str:
+    section_note = f" [{section}]" if section and section != path.stem else ""
+    return f"Rehydrated from markdown archive {path.name}{section_note}"
+
+
+def _parse_table_row(path: Path, section: str, line: str) -> LearningCandidate | None:
+    parts = [_strip_markdown(cell) for cell in line.strip().strip("|").split("|")]
+    if len(parts) < 2:
+        return None
+    title, prevention = parts[0], parts[1]
+    if title.lower() in TABLE_HEADER_TITLES or set(title) <= {"-"}:
+        return None
+    if not title or not prevention:
+        return None
+    status = "superseded" if "obsoleto" in prevention.lower() or "obsoleto" in title.lower() else "active"
+    content = f"{title}. {prevention}"
+    return LearningCandidate(
+        category=path.stem,
+        title=title,
+        content=content,
+        reasoning=_candidate_reasoning(path, section),
+        prevention=prevention,
+        status=status,
+    )
+
+
+def _consume_bullet_block(lines: list[str], start: int) -> tuple[str, int]:
+    pieces = [re.sub(r"^([-*]|\d+\.)\s+", "", lines[start].strip())]
+    idx = start + 1
+    while idx < len(lines):
+        stripped = lines[idx].strip()
+        if not stripped:
+            break
+        if stripped.startswith("## ") or stripped.startswith("|"):
+            break
+        if re.match(r"^([-*]|\d+\.)\s+", stripped):
+            break
+        pieces.append(stripped)
+        idx += 1
+    return _strip_markdown(" ".join(pieces)), idx
+
+
+def _parse_bullet(path: Path, section: str, text: str) -> LearningCandidate | None:
+    if len(text) < 12:
+        return None
+    title = _derive_title(text)
+    prevention = _derive_prevention(text)
+    status = "superseded" if "obsoleto" in text.lower() else "active"
+    return LearningCandidate(
+        category=path.stem,
+        title=title,
+        content=text,
+        reasoning=_candidate_reasoning(path, section),
+        prevention=prevention,
+        status=status,
+    )
+
+
+def parse_archive_file(path: Path) -> list[LearningCandidate]:
+    lines = path.read_text(encoding="utf-8", errors="ignore").splitlines()
+    section = path.stem
+    results: list[LearningCandidate] = []
+    idx = 0
+    while idx < len(lines):
+        stripped = lines[idx].strip()
+        if stripped.startswith("## "):
+            section = _strip_markdown(stripped[3:])
+            idx += 1
+            continue
+        if stripped.startswith("|") and not re.match(r"^\|\s*-", stripped):
+            row = _parse_table_row(path, section, stripped)
+            if row is not None:
+                results.append(row)
+            idx += 1
+            continue
+        if re.match(r"^([-*]|\d+\.)\s+", stripped):
+            block, next_idx = _consume_bullet_block(lines, idx)
+            row = _parse_bullet(path, section, block)
+            if row is not None:
+                results.append(row)
+            idx = next_idx
+            continue
+        idx += 1
+    return results
+
+
+def parse_archive_dir(archive_dir: Path) -> list[LearningCandidate]:
+    candidates: list[LearningCandidate] = []
+    for path in sorted(archive_dir.glob("*.md")):
+        candidates.extend(parse_archive_file(path))
+
+    deduped: list[LearningCandidate] = []
+    seen: set[tuple[str, str]] = set()
+    for item in candidates:
+        key = (item.category.lower(), item.title.lower())
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(item)
+    return deduped
+
+
+def resolve_archive_dir(explicit: str = "") -> Path:
+    if explicit:
+        path = Path(explicit).expanduser()
+        if not path.is_dir():
+            raise FileNotFoundError(f"archive dir not found: {path}")
+        return path
+    for candidate in DEFAULT_ARCHIVE_DIRS:
+        if candidate.is_dir():
+            return candidate
+    raise FileNotFoundError(
+        "No learnings archive found. Tried: "
+        + ", ".join(str(path) for path in DEFAULT_ARCHIVE_DIRS)
+    )
+
+
+def apply_candidates(candidates: list[LearningCandidate], *, apply: bool) -> dict:
+    init_db()
+    conn = get_db()
+    existing = {
+        (row[0].lower(), row[1].lower())
+        for row in conn.execute("SELECT category, title FROM learnings").fetchall()
+    }
+    inserted = 0
+    skipped = 0
+    for item in candidates:
+        key = (item.category.lower(), item.title.lower())
+        if key in existing:
+            skipped += 1
+            continue
+        if apply:
+            create_learning(
+                item.category,
+                item.title,
+                item.content,
+                reasoning=item.reasoning,
+                prevention=item.prevention,
+                status=item.status,
+            )
+        existing.add(key)
+        inserted += 1
+    return {
+        "parsed": len(candidates),
+        "inserted": inserted,
+        "skipped_existing": skipped,
+        "mode": "apply" if apply else "dry-run",
+    }
+
+
+def build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--archive-dir", default="", help="Override archive directory")
+    parser.add_argument("--apply", action="store_true", help="Insert parsed learnings into the DB")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_arg_parser().parse_args(argv)
+    try:
+        archive_dir = resolve_archive_dir(args.archive_dir)
+    except FileNotFoundError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+    candidates = parse_archive_dir(archive_dir)
+    summary = apply_candidates(candidates, apply=args.apply)
+    print(
+        f"{summary['mode']}: archive={archive_dir} parsed={summary['parsed']} "
+        f"inserted={summary['inserted']} skipped_existing={summary['skipped_existing']}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/server.py

@@ -202,6 +202,8 @@ mcp = FastMCP(
         "- **Workflow runtime (MANDATORY for long multi-step or cross-session work):** open `nexo_goal_open(...)` when the objective must survive sessions, then `nexo_workflow_open(...)`, "
         "update meaningful checkpoints with `nexo_workflow_update(...)`, then use `nexo_workflow_resume(...)` / "
         "`nexo_workflow_replay(...)` instead of restarting blindly.\n"
+        "- **Diagnostic plane (MANDATORY before diagnosing NEXO):** fix the plane explicitly first — `product_public`, `runtime_personal`, `installation_live`, `database_real`, or `cooperator`. "
+        "Do not mix product, runtime, install, DB, and agent-behavior explanations in the same diagnosis.\n"
         "- **Guard (MANDATORY before ANY code edit):** `nexo_guard_check(files='...', area='...')` BEFORE editing code. "
         "No exceptions. Blocking rules→resolve first. `nexo_track(sid=SID, paths=[...])` before shared files\n"
         "- **Skills (MANDATORY before multi-step tasks):** `nexo_skill_match(task)` to find reusable procedures. "